QThread Class

Documentation des fonctions membres

[explicit] QThread::QThread(QObject *parent = nullptr)

Crée un nouvel objet QThread pour gérer un nouveau thread. L'parent prend possession du QThread. Le thread ne commence pas à s'exécuter tant que la fonction start() n'a pas été appelée.

Voir également start().

[virtual noexcept] QThread::~QThread()

Supprime l'objet ` QThread`.

Notez que la suppression d’un objet ` QThread ` n’interrompt pas l’exécution du thread qu’il gère. La suppression d’un ` QThread ` en cours d’exécution (c’est-à-dire lorsque ` isFinished()` renvoie ` false`) entraînera un plantage du programme. Attendez le signal ` finished()` avant de supprimer le ` QThread`.

Depuis Qt 6.3, il est possible de supprimer une instance de ` QThread ` créée par un appel à ` QThread::create()` même si le thread correspondant est toujours en cours d'exécution. Dans ce cas, Qt envoie une demande d’interruption à ce thread (via ` requestInterruption()`) ; demande à la boucle d’événements du thread (le cas échéant) de se fermer (via ` quit()`) ; et se bloque jusqu’à ce que le thread ait terminé.

Voir également create(), isInterruptionRequested(), exec() et quit().

[static] template <typename Function, typename... Args> QThread *QThread::create(Function &&f, Args &&... args)

Crée un nouvel objet ` QThread ` qui exécutera la fonction ` f ` avec les arguments ` args`.

Le nouveau thread n’est pas lancé : il doit l’être par un appel explicite à start(). Cela vous permet de vous connecter à ses signaux, de déplacer des QObjects vers le thread, de choisir la priorité du nouveau thread, etc. La fonction f sera appelée dans le nouveau thread.

Renvoie l'instance QThread nouvellement créée.

Voir également start().

[static] QThread *QThread::currentThread()

Renvoie un pointeur vers une instance de ` QThread ` qui gère le thread en cours d'exécution.

[static noexcept] Qt::HANDLE QThread::currentThreadId()

Renvoie le descripteur du thread en cours d'exécution.

[override virtual] bool QThread::event(QEvent *event)

Réimplémente : QObject::event(QEvent *e).

QAbstractEventDispatcher *QThread::eventDispatcher() const

Renvoie un pointeur vers l'objet « event dispatcher » du thread. Si aucun « event dispatcher » n'existe pour ce thread, cette fonction renvoie ` nullptr`.

Voir également setEventDispatcher().

[protected] int QThread::exec()

Entre dans la boucle d'événements et attend que la fonction ` exit()` soit appelée, en renvoyant la valeur qui a été transmise à ` exit()`. La valeur renvoyée est 0 si la fonction ` exit()` est appelée via ` quit()`.

Cette fonction est destinée à être appelée depuis l'intérieur de run(). Il est nécessaire d'appeler cette fonction pour lancer la gestion des événements.

Voir également quit() et exit().

[slot] void QThread::exit(int returnCode = 0)

Indique à la boucle d'événements du thread de se terminer avec un code de retour.

Après l'appel de cette fonction, le thread quitte la boucle d'événements et revient de l'appel à QEventLoop::exec(). La fonction QEventLoop::exec() renvoie returnCode.

Par convention, une valeur de ` returnCode ` égale à 0 signifie que l'opération a réussi ; toute valeur différente de zéro indique une erreur.

Notez que, contrairement à la fonction de la bibliothèque C du même nom, cette fonction revient bien à l’appelant : c’est le traitement des événements qui s’arrête.

Aucune boucle d’événements (QEventLoop) ne sera plus lancée dans ce thread tant que la fonction QThread::exec() n’aura pas été appelée à nouveau. Si la boucle d’événements de QThread::exec() n’est pas en cours d’exécution, le prochain appel à QThread::exec() renverra également une valeur immédiatement.

Remarque : cette fonction est thread-safe.

Voir également quit() et QEventLoop.

[private signal] void QThread::finished()

Ce signal est émis par le thread associé juste avant la fin de son exécution.

Lorsque ce signal est émis, la boucle d'événements a déjà cessé de s'exécuter. Aucun autre événement ne sera traité dans le thread, à l'exception des événements de suppression différée. Ce signal peut être associé à la fonction QObject::deleteLater(), afin de libérer les objets dans ce thread.

Voir également started().

[static noexcept] int QThread::idealThreadCount()

Renvoie le nombre idéal de threads que ce processus peut exécuter en parallèle. Pour ce faire, la fonction interroge le nombre de processeurs logiques disponibles pour ce processus (si cette fonctionnalité est prise en charge par le système d'exploitation) ou le nombre total de processeurs logiques du système. Cette fonction renvoie 1 si aucune de ces deux valeurs n'a pu être déterminée.

[noexcept, since 6.8] bool QThread::isCurrentThread() const

Renvoie « true » si ce thread est de type « QThread::currentThread ».

Cette fonction a été introduite dans Qt 6.8.

Voir également currentThreadId().

bool QThread::isFinished() const

Renvoie ` true ` si le thread est terminé ; sinon, renvoie ` false`.

Un thread est considéré comme terminé s’il est revenu de la fonction run() et si le signal finished() a été émis.

Notez que le thread peut encore s’exécuter pendant un temps indéterminé après l’émission du signal ` finished()`, afin d’effectuer des opérations de nettoyage telles que l’exécution des destructeurs des variables ` thread_local `. Pour synchroniser tous les effets du thread, appelez ` wait()` et vérifiez qu’elle renvoie `true`.

Remarque : cette fonction est thread-safe.

Voir également isRunning().

bool QThread::isInterruptionRequested() const

Renvoie `true` si la tâche s'exécutant sur ce thread doit être interrompue. Une interruption peut être demandée par la fonction ` requestInterruption()`.

Cette fonction permet de rendre les tâches de longue durée facilement interrompables. Il est sans risque de ne jamais vérifier ni tenir compte de la valeur renvoyée par cette fonction ; il est toutefois conseillé de le faire régulièrement dans les fonctions de longue durée. Veillez à ne pas l'appeler trop souvent, afin de limiter la surcharge.

void long_task() {
     forever {
        if ( QThread::currentThread()->isInterruptionRequested() ) {
            return;
        }
    }
}

Voir également currentThread() et requestInterruption().

[static noexcept, since 6.8] bool QThread::isMainThread()

Indique si le thread en cours d'exécution est le thread principal.

Le thread principal est celui dans lequel QCoreApplication a été créé. Il s'agit généralement du thread qui a appelé la fonction main(), mais ce n'est pas nécessairement le cas. C'est le thread qui traite les événements de l'interface graphique et dans lequel des objets graphiques (QWindow, QWidget) peuvent être créés.

Cette fonction a été introduite dans Qt 6.8.

Voir également currentThread() et QCoreApplication::instance().

bool QThread::isRunning() const

Renvoie ` true ` si le thread est en cours d'exécution ; sinon, renvoie ` false`.

Un thread est considéré comme en cours d'exécution si QThread a été lancé avec start() mais n'est pas encore terminé.

Notez que le thread peut encore s’exécuter pendant une durée indéterminée après l’émission du signal ` finished()`, afin d’effectuer des opérations de nettoyage telles que l’exécution des destructeurs des variables ` thread_local `. Pour synchroniser tous les effets du thread, appelez ` wait()` et vérifiez qu’elle renvoie `true`.

Remarque : cette fonction est thread-safe.

Voir également isFinished().

int QThread::loopLevel() const

Renvoie le niveau actuel de la boucle d'événements pour le thread.

[static] void QThread::msleep(unsigned long msecs)

Il s'agit d'une fonction surchargée, équivalente à l'appel suivant :

QThread::sleep(std::chrono::milliseconds{msecs});

Voir également sleep() et usleep().

QThread::Priority QThread::priority() const

Renvoie la priorité d'un thread en cours d'exécution. Si le thread n'est pas en cours d'exécution, cette fonction renvoie « InheritPriority ».

Voir également Priority, setPriority() et start().

[slot] void QThread::quit()

Indique à la boucle d'événements du thread de se terminer avec un code de retour égal à 0 (succès). Cela revient à appeler la fonction ` QThread::exit(0)`.

Cette fonction ne fait rien si le thread ne dispose pas d'une boucle d'événements.

Remarque : cette fonction est sûre pour les threads.

Voir également exit() et QEventLoop.

void QThread::requestInterruption()

Demande l'interruption du thread. Cette demande est à titre indicatif et il appartient au code s'exécutant sur le thread de décider s'il doit y donner suite et, le cas échéant, de quelle manière. Cette fonction n'arrête aucune boucle d'événements s'exécutant sur le thread et ne le termine en aucune manière.

Cette fonction n'a aucun effet sur le thread principal et ne fait rien si le thread n'est pas en cours d'exécution.

Remarque : cette fonction est sûre pour les threads.

Voir également ` isInterruptionRequested()`.

[virtual protected] void QThread::run()

Point de départ du thread. Après l'appel à ` start()`, le thread nouvellement créé appelle cette fonction. L'implémentation par défaut se contente d'appeler ` exec()`.

Vous pouvez réimplémenter cette fonction pour faciliter la gestion avancée des threads. Le retour de cette méthode mettra fin à l'exécution du thread.

Voir également start() et wait().

[since 6.9] QThread::QualityOfService QThread::serviceLevel() const

Renvoie le niveau actuel de qualité de service (QoS) du thread.

Cette fonction a été introduite dans Qt 6.9.

Voir également setServiceLevel() et QThreadPool::serviceLevel().

void QThread::setEventDispatcher(QAbstractEventDispatcher *eventDispatcher)

Définit le gestionnaire d'événements du thread sur eventDispatcher. Cela n'est possible que si aucun gestionnaire d'événements n'a encore été installé pour ce thread.

Un répartiteur d’événements est automatiquement créé pour le thread principal lors de l’instanciation de ` QCoreApplication ` et lors de l’appel de ` start()` pour les threads auxiliaires.

Cette méthode prend possession de l’objet.

Voir également ` eventDispatcher()`.

void QThread::setPriority(QThread::Priority priority)

Cette fonction définit l'priority e d'un thread en cours d'exécution. Si le thread n'est pas en cours d'exécution, cette fonction ne fait rien et renvoie immédiatement une valeur. Utilisez start() pour lancer un thread avec une priorité spécifique.

L'argument ` priority ` peut prendre n'importe quelle valeur de l'énumération ` QThread::Priority `, à l'exception de ` InheritPriority`.

L’effet du paramètre priority dépend de la politique d’ordonnancement du système d’exploitation. En particulier, la valeur priority sera ignorée sur les systèmes qui ne prennent pas en charge les priorités de threads (comme sous Linux ; voir http://linux.die.net/man/2/sched_setscheduler pour plus de détails).

Voir également Priority, priority() et start().

[since 6.9] void QThread::setServiceLevel(QThread::QualityOfService serviceLevel)

Définissez le niveau de qualité de service (QoS) de l'objet thread sur « serviceLevel ». Cette fonction ne peut être appelée qu'à partir du thread lui-même ou avant le démarrage de celui-ci !

Cette fonctionnalité n’est actuellement implémentée que sur les plateformes Apple et sous Windows. L’appel de fonction s’exécutera correctement sur les autres plateformes, mais n’aura pour l’instant aucun effet.

Cette fonction a été introduite dans Qt 6.9.

Voir également ` serviceLevel()` et ` QThreadPool::setServiceLevel()`.

void QThread::setStackSize(uint stackSize)

Définit la taille de la pile du thread à stackSize octets. Si la valeur de ` stackSize ` est égale à zéro, le système d’exploitation ou le moteur d’exécution choisira une valeur par défaut. Dans le cas contraire, la taille de la pile du thread correspondra à la valeur fournie (qui pourra être arrondie à l’unité supérieure ou inférieure).

Sur la plupart des systèmes d’exploitation, la quantité de mémoire allouée à la pile sera initialement inférieure à stackSize et augmentera à mesure que le thread utilise la pile. Ce paramètre définit la taille maximale jusqu’à laquelle elle sera autorisée à croître (c’est-à-dire qu’il définit la taille de l’espace de mémoire virtuelle que la pile est autorisée à occuper).

Cette fonction ne peut être appelée qu’avant le démarrage du thread.

Voir également stackSize().

[static protected] void QThread::setTerminationEnabled(bool enabled = true)

Active ou désactive la terminaison du thread actuel en fonction du paramètre ` enabled `. Le thread doit avoir été lancé par la fonction ` QThread`.

Lorsque enabled est faux, la terminaison est désactivée. Les futurs appels à QThread::terminate() renverront immédiatement une valeur sans effet. La terminaison est alors reportée jusqu’à ce qu’elle soit activée.

Lorsque enabled est à « true », la terminaison est activée. Les futurs appels à QThread::terminate() mettront fin au thread normalement. Si la terminaison a été reportée (c'est-à-dire si QThread::terminate() a été appelée avec la terminaison désactivée), cette fonction mettra immédiatement fin au thread appelant. Notez que cette fonction ne renverra pas de résultat dans ce cas.

Voir également terminate().

[static, since 6.6] void QThread::sleep(std::chrono::nanoseconds nsecs)

Force le thread actuel à se mettre en veille pendant nsecs.

Évitez d’utiliser cette fonction si vous devez attendre qu’une condition donnée change. Connectez plutôt un slot au signal indiquant ce changement ou utilisez un gestionnaire d’événements (voir QObject::event()).

Cette fonction a été introduite dans Qt 6.6.

[static] void QThread::sleep(unsigned long secs)

Force le thread actuel à se mettre en veille pendant secs s de secondes.

Il s'agit d'une fonction surchargée, équivalente à l'appel de :

QThread::sleep(std::chrono::seconds{secs});

Voir également msleep() et usleep().

uint QThread::stackSize() const

Renvoie la taille maximale de la pile pour le thread en octets (si elle a été définie via ` setStackSize()`) ; sinon, renvoie zéro.

Voir également setStackSize().

[slot] void QThread::start(QThread::Priority priority = InheritPriority)

Lance l'exécution du thread en appelant la fonction ` run()`. Le système d'exploitation planifiera le thread conformément au paramètre ` priority `. Si le thread est déjà en cours d'exécution, cette fonction ne fait rien.

L'effet du paramètre priority dépend de la politique de planification du système d'exploitation. En particulier, priority sera ignoré sur les systèmes qui ne prennent pas en charge les priorités de threads (comme sous Linux ; voir la documentation de sched_setscheduler pour plus de détails).

Voir également run() et terminate().

[private signal] void QThread::started()

Ce signal est émis par le thread associé dès qu’il commence à s’exécuter ; ainsi, tous les slots qui lui sont associés peuvent être appelés via une invocation mise en file d’attente. Même si l’événement a pu être publié avant l’appel de run(), la transmission du signal entre threads peut encore être en attente.

Voir également ` run()` et ` finished()`.

[slot] void QThread::terminate()

Mette fin à l'exécution du thread. Le thread peut être arrêté immédiatement ou non, selon les politiques d'ordonnancement du système d'exploitation. Pour plus de sécurité, utilisez ` QThread::wait()` après `terminate()`.

Lorsque le thread est interrompu, tous les threads en attente de sa fin sont réveillés.

La terminaison peut être explicitement activée ou désactivée en appelant ` QThread::setTerminationEnabled()`. L'appel de cette fonction alors que la terminaison est désactivée entraîne le report de la terminaison jusqu'à ce que celle-ci soit réactivée. Consultez la documentation de ` QThread::setTerminationEnabled()` pour plus d'informations.

Remarque : cette fonction est sûre pour les threads.

Voir également setTerminationEnabled().

[static] void QThread::usleep(unsigned long usecs)

Il s'agit d'une fonction surchargée, équivalente à l'appel suivant :

QThread::sleep(std::chrono::microseconds{secs});

Voir également sleep() et msleep().

bool QThread::wait(QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))

Bloque le thread jusqu'à ce que l'une des deux conditions suivantes soit remplie :

• Le thread associé à cet objet ` QThread ` a terminé son exécution (c'est-à-dire lorsqu'il revient de la fonction ` run()`). Cette fonction renvoie `true` si le thread a terminé. Elle renvoie également `true` si le thread n'a pas encore été lancé.
• L'deadline est atteinte. Cette fonction renvoie « false » si la date limite est atteinte.

Un minuteur de délai défini sur QDeadlineTimer::Forever (valeur par défaut) n’expirera jamais : dans ce cas, la fonction ne renvoie une valeur que lorsque le thread revient de la fonction run() ou si le thread n’a pas encore démarré.

Cela offre une fonctionnalité similaire à celle de la fonction POSIX pthread_join().

Voir également ` sleep()` et ` terminate()`.

bool QThread::wait(unsigned long time)

time est le temps d'attente en millisecondes. Si time vaut ULONG_MAX, l'attente n'expirera jamais.

[static] void QThread::yieldCurrentThread()

Cède l'exécution du thread actuel à un autre thread prêt à s'exécuter, s'il y en a un. Notez que c'est le système d'exploitation qui décide vers quel thread basculer.