QThread Class

Documentation des fonctions membres

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

Construit un nouveau QThread pour gérer un nouveau thread. L'adresse parent devient propriétaire du QThread. Le thread ne commence pas à s'exécuter tant que start() n'est pas appelé.

Voir également start().

[virtual noexcept] QThread::~QThread()

Détruit l'objet QThread.

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

Depuis Qt 6.3, il est permis de supprimer une instance 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 XML enverra une demande d'interruption à ce thread (via requestInterruption()) ; demandera à la boucle d'événements du thread (s'il y en a une) de quitter (via quit()) ; et se bloquera 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 démarré - 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 aussi start().

[static] QThread *QThread::currentThread()

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

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

Renvoie l'identifiant 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 de distribution d'événements pour le thread. S'il n'existe pas de distributeur d'événements pour le thread, cette fonction renvoie nullptr.

Voir également setEventDispatcher().

[protected] int QThread::exec()

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

Cette fonction est destinée à être appelée à partir de run(). Il est nécessaire d'appeler cette fonction pour commencer le traitement des événements.

Voir également quit() et exit().

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

Indique à la boucle événementielle du thread de sortir avec un code de retour.

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

Par convention, un returnCode de 0 signifie un succès, toute valeur non nulle indique une erreur.

Notez que , contrairement à la fonction du même nom de la bibliothèque C, cette fonction renvoie à l'appelant - c'est le traitement de l'événement qui s'arrête.

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

Remarque : cette fonction est à l'épreuve des threads.

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 s'est déjà arrêtée. Plus aucun événement ne sera traité dans le fil d'exécution, à l'exception des événements de suppression différée. Ce signal peut être connecté à QObject::deleteLater(), pour libérer des objets dans ce thread.

Voir aussi 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, elle interroge le nombre de processeurs logiques disponibles pour ce processus (s'il est pris en charge par ce système d'exploitation) ou le nombre total de processeurs logiques dans le système. Cette fonction renvoie 1 si aucune valeur n'a pu être déterminée.

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

Retourne true si ce thread est QThread::currentThread.

Cette fonction a été introduite dans Qt 6.8.

Voir aussi 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 que le signal finished() a été émis.

Notez que le thread peut encore s'exécuter pendant une durée arbitraire après l'émission du signal finished(), en effectuant des opérations de nettoyage telles que l'exécution des destructeurs des variables thread_local. Pour se synchroniser avec tous les effets du thread, appelez wait() et vérifiez qu'il a renvoyé true.

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

Voir aussi isRunning().

bool QThread::isInterruptionRequested() const

Retourne true si la tâche en cours d'exécution sur ce thread doit être arrêtée. Une interruption peut être demandée par requestInterruption().

Cette fonction peut être utilisée pour rendre les tâches de longue durée proprement interruptibles. Ne jamais vérifier ou agir sur la valeur renvoyée par cette fonction est sûr, mais il est conseillé de le faire régulièrement dans les fonctions qui s'exécutent depuis longtemps. Veillez à ne pas l'appeler trop souvent, afin de maintenir l'overhead à un niveau bas.

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

Voir aussi 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 le thread dans lequel QCoreApplication a été créé. Il s'agit généralement du thread qui a appelé la fonction main(), mais pas nécessairement. C'est le thread qui traite les événements de l'interface graphique et dans lequel les objets graphiques (QWindow, QWidget) peuvent être créés.

Cette fonction a été introduite dans Qt 6.8.

Voir aussi currentThread() et QCoreApplication::instance().

bool QThread::isRunning() const

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

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

Notez que le thread peut encore s'exécuter pendant une durée arbitraire après l'émission du signal finished(), en effectuant des opérations de nettoyage telles que l'exécution des destructeurs des variables thread_local. Pour se synchroniser avec tous les effets du thread, appelez wait() et vérifiez qu'il a renvoyé true.

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

Voir aussi isFinished().

int QThread::loopLevel() const

Renvoie le niveau actuel de la boucle d'événements pour le fil d'exécution.

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

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

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

Voir aussi 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 quitter avec le code de retour 0 (succès). Cela équivaut à appeler QThread::exit(0).

Cette fonction ne fait rien si le thread n'a pas de boucle d'événements.

Remarque : cette fonction est sans danger pour les threads.

Voir aussi exit() et QEventLoop.

void QThread::requestInterruption()

Demander l'interruption du fil de discussion. Cette demande est consultative et c'est au code s'exécutant sur le fil de décider si et comment il doit agir en fonction de cette demande. Cette fonction n'arrête aucune boucle d'événements en cours d'exécution sur le thread et ne le termine en aucune façon.

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 sans danger pour les threads.

Voir également isInterruptionRequested().

[virtual protected] void QThread::run()

Le point de départ du fil de discussion. Après avoir appelé start(), le nouveau fil de discussion appelle cette fonction. L'implémentation par défaut appelle simplement exec().

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

Voir également start() et wait().

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

Renvoie le niveau de qualité de service actuel du thread.

Cette fonction a été introduite dans Qt 6.9.

Voir aussi setServiceLevel() et QThreadPool::serviceLevel().

void QThread::setEventDispatcher(QAbstractEventDispatcher *eventDispatcher)

Définit le distributeur d'événements pour le thread à eventDispatcher. Cela n'est possible que si aucun distributeur d'événements n'est encore installé pour le thread.

Un distributeur d'événements est automatiquement créé pour le thread principal lors de l'instanciation de QCoreApplication et sur start() pour les threads auxiliaires.

Cette méthode prend possession de l'objet.

Voir aussi eventDispatcher().

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

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

L'argument priority peut être 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, le paramètre priority sera ignoré sur les systèmes qui ne prennent pas en charge les priorités des threads (comme sous Linux, voir http://linux.die.net/man/2/sched_setscheduler pour plus de détails).

Voir aussi Priority, priority(), et start().

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

Fixe le niveau de qualité de service de l'objet thread à serviceLevel. Cette fonction ne peut être appelée qu'à partir du thread lui-même ou avant que le thread ne soit démarré !

Cette fonction n'est actuellement mise en œuvre que sur les plates-formes Apple et Windows. L'appel de la fonction s'effectuera avec succès sur d'autres plateformes, mais n'aura aucun effet pour le moment.

Cette fonction a été introduite dans Qt 6.9.

Voir aussi serviceLevel() et QThreadPool::setServiceLevel().

void QThread::setStackSize(uint stackSize)

Définit la taille de la pile pour le thread à stackSize. Si stackSize est zéro, le système d'exploitation ou le runtime choisira une valeur par défaut. Sinon, la taille de la pile du thread sera la valeur fournie (qui peut être arrondie vers le haut ou vers le bas).

Sur la plupart des systèmes d'exploitation, la quantité de mémoire allouée à la pile sera initialement inférieure à stackSize et augmentera au fur et à mesure que le thread utilisera la pile. Ce paramètre définit la taille maximale de la pile (c'est-à-dire la taille de l'espace mémoire virtuel 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 fin de la discussion en cours en fonction du paramètre enabled. La discussion doit avoir été lancée par QThread.

Lorsque enabled est faux, la terminaison est désactivée. Les futurs appels à QThread::terminate() reviendront immédiatement sans effet. Au lieu de cela, la terminaison est différée jusqu'à ce que la terminaison soit activée.

Lorsque enabled est vrai, la terminaison est activée. Les prochains appels à QThread::terminate() mettront fin au thread normalement. Si la terminaison a été différée (c'est-à-dire que QThread::terminate() a été appelé alors que la terminaison était désactivée), cette fonction terminera immédiatement le thread appelant. Notez que cette fonction ne renvoie pas dans ce cas.

Voir aussi terminate().

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

Force le thread en cours à dormir pendant nsecs.

Évitez d'utiliser cette fonction si vous devez attendre qu'une condition donnée change. Au lieu de cela, connectez un slot au signal qui indique le 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 en cours à dormir pendant secs secondes.

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

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

Voir aussi msleep() et usleep().

uint QThread::stackSize() const

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

Voir aussi setStackSize().

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

Commence l'exécution du thread en appelant run(). Le système d'exploitation planifie l'exécution du thread en fonction du 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 d'ordonnancement du système d'exploitation. En particulier, le paramètre priority sera ignoré sur les systèmes qui ne prennent pas en charge les priorités des threads (comme sous Linux, voir la documentation sched_setscheduler pour plus de détails).

Voir aussi run() et terminate().

[private signal] void QThread::started()

Ce signal est émis par le thread associé lorsqu'il commence à s'exécuter, de sorte que tous les slots qui lui sont connectés peuvent être appelés par le biais d'une invocation en file d'attente. Bien que l'événement puisse avoir été posté avant que run() ne soit appelé, toute transmission du signal entre threads peut encore être en attente.

Voir aussi run() et finished().

[slot] void QThread::terminate()

Termine l'exécution du thread. Le thread peut être terminé immédiatement ou non, en fonction de la politique d'ordonnancement du système d'exploitation. Pour vous en assurer, utilisez QThread::wait() après terminate().

Lorsque le thread est terminé, tous les threads qui attendent la fin du thread sont réveillés.

La terminaison peut être explicitement activée ou désactivée en appelant QThread::setTerminationEnabled(). L'appel à cette fonction alors que la terminaison est désactivée a pour effet de différer la terminaison jusqu'à ce qu'elle soit réactivée. Voir 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 :

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 de ces conditions soit remplie :

• Le thread associé à cet objet QThread a terminé son exécution (c'est-à-dire lorsqu'il revient de run()). Cette fonction renvoie un message vrai si l'exécution de la discussion est terminée. Elle renvoie également un résultat positif si la discussion n'a pas encore été lancée.
• L'échéance deadline est atteinte. Cette fonction renvoie un message faux si l'échéance est atteinte.

Un timer de date limite réglé sur QDeadlineTimer::Forever (par défaut) n'est jamais dépassé : dans ce cas, la fonction ne revient que lorsque le thread revient de run() ou si le thread n'a pas encore démarré.

Cette fonction est similaire à 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 est ULONG_MAX, le délai d'attente ne sera jamais dépassé.

[static] void QThread::yieldCurrentThread()

Transfère l'exécution du thread actuel à un autre thread exécutable, s'il y en a un. Notez que c'est le système d'exploitation qui décide vers quelle thread basculer.