QThread

La classe QThread fournit des threads indépendants de la plateforme. Plus d'informations...

#include <QThread>

Héritage

Hérite de QObject.

Description détaillée

La classe QThread fournit des threads indépendants de la plateforme.

Un QThread représente un thread de contrôle séparé dans le programme ; il partage des données avec tous les autres threads dans le processus mais s'exécute de manière indépendante, comme un programme séparé sur un système d'exploitation multi-tâches. Au lieu de démarrer dans main(), un QThread débute son exécution dans run(). Par défaut, run() démarre la boucle événementielle en appelant exec() (voir ci-après). Pour créer vos propres threads, dérivez de QThread et réimplémentez run(). Par exemple :

class MyThread : public QThread
{
public:
    void run();
};
 
void MyThread::run()
{
    QTcpSocket socket;
    // connectez les signaux de QTcpSocket là où cela a du sens
    ...
    socket.connectToHost(hostName, portNumber);
    exec();
}

Ce code va créer un QTcpSocket dans le thread et exécuter la boucle événementielle du thread. Utilisez la méthode start() pour commencer l'exécution, qui finit quand vous retournez depuis run(), exactement comme une application fait quand elle quitte main(). QThread vous préviendra via un signal quand le thread est lancé, fini et terminé ; alternativement, vous pouvez utiliser isFinished() et isRunning() pour demander l'état du thread. Utilisez wait() pour bloquer jusqu'à ce que le thread ait fini son exécution.

Chaque thread possède sa propre pile grâce au système d'exploitation, qui détermine aussi sa taille par défaut. Vous pouvez utiliser setStackSize() pour définir une taille de pile personnalisée.

Chaque QThread peut avoir sa propre boucle événementielle. Vous pouvez démarrer cette boucle en appelant exec() et l'arrêter avec exit() ou quit(). Avoir une telle boucle dans un thread rend possible la connexion de signaux d'autres threads à des slots dans ce thread, en utilisant un mécanisme appelé les connexions mises en queue. Elle rend aussi possible l'utilisation des classes qui en requièrent une, comme QTimer et QTcpSocket, dans le thread. Notez, cependant, qu'il n'est pas possible d'utiliser la moindre classe widget dans le thread.

Dans des cas extrêmes, vous pourriez vouloir terminer d'une manière forcée un thread en cours d'exécution. Agir ainsi est dangereux et déconseillé. Merci de lire la documentation de terminate() et de setTerminationEnabled() pour plus d'informations.

Les fonctions statiques currentThreadId() et currentThread() retournent des identifiants pour les threads actuellement en cours d'exécution. La première retourne un identifiant spécifique à la plateforme ; la seconde retourne un pointeur sur QThread.

QThread fournit aussi des fonctions de type sleep indépendantes de la plateforme et à différentes résolutions. Utilisez sleep() pour une précision à la seconde, msleep() à la milliseconde et usleep() à la microseconde.

Voir aussi Le support des threads dans Qt, QThreadStorage, QMutex, QSemaphore, QWaitCondition, l'exemple Mandelbrot, l'exemple Semaphores et l'exemple Wait Conditions.

Type

enum QThread::Priority

Cette énumération indique la manière dont le système d'exploitation devrait programmer les threads nouvellement créés.

Fonctions membres

QThread::QThread ( QObject * parent = 0 )

Construit un nouveau thread avec le parent donné. Le thread n'est pas exécuté tant que la fonction start() n'a pas été appelée.

Voir aussi start().

QThread::~QThread ()

Détruit le thread.

Notez que détruire un objet QThread ne va pas stopper l'exécution du thread qu'il représente. Supprimer un QThread en cours d'exécution (c'est-à-dire que isFinished() retourne false) va probablement crasher le programme. Vous pouvez attendre un thread pour vous assurer qu'il a terminé.

QThread * QThread::currentThread () [static]

Retourne un pointeur sur un QThread qui représente le thread en cours d'exécution.

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

Retourne le handle du thread en cours d'exécution.

Attention : le handle retourné par cette fonction est utilisé à des fins internes et ne devrait être utilisé dans aucun code d'application.

Attention : sous Windows, la valeur retournée est un pseudo-handle pour le thread courant. Il ne peut pas être utilisé pour des comparaisons numériques, c'est-à-dire que cette fonction retourne un DWORD (Windows-Thread ID) tel que retourné par la fonction de l'API Win32 getCurrentThreadId(), pas le HANDLE (Windows-Thread HANDLE) retourné par la fonction de l'API Win32 getCurrentThread().

int QThread::exec () [protected]

Entre dans la boucle événementielle et attend jusqu'à ce que exit() soit appelé, retournant la valeur passée à exit(). La valeur retournée est 0 si exit() est appelé via quit().

Il est nécessaire d'appeler cette fonction pour démarrer la gestion des événements.

Voir aussi quit() et exit().

void QThread::exit ( int returnCode = 0 )

Demande à la boucle événementielle du thread de quitter avec un code de retour.

Après avoir appelé cette fonction, le thread quitte la boucle événementielle et retourne de l'appel à QEventLoop::exec(). La fonction QEventLoop::exec() retournera returnCode.

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

Notez que, au contraire de la fonction de la bibliothèque standard C du même nom, cette fonction ne retourne pas à l'appelant - c'est le traitement des événements qui s'arrête.

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

Voir aussi quit() et QEventLoop.

void QThread::finished () [signal]

Ce signal est émis quand le thread a fini son exécution.

Voir aussi started() et terminated().

int QThread::idealThreadCount () [static]

Retourne le nombre idéal de threads à lancer sur le système. Ce résultat est obtenu en demandant le nombre de c?urs du processeur, physiques et logiques. Cette fonction retourne -1 si le nombre de c?urs ne peut pas être détecté.

bool QThread::isFinished () const

Retourne true si le thread a terminé son exécution, false sinon.

Voir aussi isRunning().

bool QThread::isRunning () const

Retourne true si le thread est en cours d'exécution, false sinon.

Voir aussi isFinished().

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

Le thread actuel attendra msecs millisecondes.

Voir aussi sleep() et usleep().

Priority QThread::priority () const

Retourne la priorité du thread en cours d'exécution. Si le thread ne l'est pas, cette fonction retourne InheritPriority.

Cette fonction a été introduite dans Qt 4.1.

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

void QThread::quit () [slot]

Demande à la boucle événementielle du thread de quitter avec 0 comme code de retour (succès). Cette fonction est équivalente à un appel à QThread::exit(0).

Cette fonction ne fait rien s'il n'y a pas de boucle événementielle.

Voir aussi exit() et QEventLoop.

void QThread::run () [virtual protected]

Le point d'entrée du thread. Après l'appel à start(), le thread nouvellement créé appelle cette fonction. L'implémentation par défaut appelle simplement exec().

Vous pouvez réimplémenter cette fonction pour réaliser un travail utile. Retourner depuis cette méthode causera la fin de l'exécution du thread.

Voir aussi start() et wait().

void QThread::setPriority ( Priority priority )

Cette fonction définit la priorité du thread actuel. 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 InheritPriorty.

L'effet de ce paramètre dépend de la politique de programmation du système d'exploitation. En particulier, la priorité sera ignorée sur les systèmes ne supportant pas les priorités de threads (comme sous Linux, voir http://linux.die.net/man/2/sched_setscheduler pour plus de détails).

Cette fonction a été introduite dans Qt 4.1.

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

void QThread::setStackSize ( uint stackSize )

Définit la talle maximale de la pile du thread à stackSize. Si stackSize est strictement positive, la taille maximale de la pile est définie à stackSize octets, sinon elle est automatiquement déterminée par le système d'exploitation.

Attention : la plupart des systèmes d'exploitation placent des limites en minimum et maximum sur les tailles de pile des threads. Le thread ne pourra pas démarrer si la taille de la pile est en dehors de ces limites.

Voir aussi stackSize().

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

Active ou désactive l'interruption du thread courant en se basant sur le paramètre enabled. Le thread doit avoir été démarré par QThread.

Quand enabled est à false, l'interruption est désactivée. Les appels futurs à QThread::terminate() retourneront directement sans effet, l'interruption est différée jusqu'à ce que l'interruption soit à nouveau activée.

Quand enabled est à true, l'interruption est activée. Les appels futurs à QThread::terminate() termineront le thread normalement. Si une interruption a été différée (c'est-à-dire si QThread::terminate() a été précédemment appelé pour la désactiver), cette fonction terminera immédiatement le thread appelant. Notez que cette fonction ne retournera pas dans ce cas.

Voir aussi terminate().

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

Force le thread actuel à dormir pendant secs secondes.

Voir aussi msleep() et usleep().

uint QThread::stackSize () const

Retourne la taille maximale de la pile du thread si elle a été définie avec setStackSize(), sinon retourne 0.

Voir aussi setStackSize().

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

Débute l'exécution du thread en appelant run(), qui devrait être réimplémentée dans un dérivé de QThread pour contenir votre code. Le système d'exploitation programmera le thread en fonction du paramètre priority. Si le thread est déjà lancé, cette fonction ne fait rien.

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

Voir aussi run() et terminate().

void QThread::started () [signal]

Ce signal est émis quand le thread commence son exécution.

Voir aussi finished() et terminated().

void QThread::terminate () [slot]

Termine l'exécution du thread. Le thread peut ne pas être terminé immédiatement, selon le système d'exploitation et ses politiques de programmation. Utilisez QThread::wait() après cette fonction pour une fin synchrone.

Quand le thread est terminé, tous les thread attendant sa fin seront réveillés.

Attention : cette fonction est dangereuse et son utilisation est déconseillée. Le thread peut être terminé à n'importe quel point de son code. Il pourrait être terminé pendant la modification de données. Il n'y a pas moyen que le thread nettoie après son passage, débloque le moindre mutex, etc. En bref, n'utilisez cette fonction que si cela est réellement nécessaire.

L'interruption peut être explicitement activée ou désactivée en appelant QThread::setTerminationEnabled(). Appeler cette fonction pendant que l'interruption est désactivée fait que l'interruption est différée. Voir la documentation de QThread::setTerminationEnabled() pour plus d'informations.

Voir aussi setTerminationEnabled().

void QThread::terminated () [signal]

Ce signal est émis quand le thread est interrompu.

Voir aussi started() et finished().

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

Fait en sorte que le thread actuel dorme pour usecs microsecondes.

Voir aussi sleep() et msleep().

bool QThread::wait ( unsigned long time = ULONG_MAX )

Bloque le thread jusqu'à ce qu'une de ces conditions soit rencontrée :

• le thread associé à ce QThread a terminé son exécution (c'est-à-dire qu'il retourne de run()) ; cette fonction retournera true si le thread est fini ou si le thread n'a pas encore été démarré ;
• time millisecondes se sont écoulées ; si time vaut ULONG_MAX (la valeur par défaut), cette fonction ne se finira jamais (le thread devra retourner de run()) ; cette fonction retournera false si le temps est écoulé avant que le thread soit fini.

Cette fonction fournit des fonctionnalités similaires à la fonction POSIX pthread_join().

Voir aussi sleep() et terminate().

void QThread::yieldCurrentThread () [static]

Cède l'exécution du thread actuel à un autre thread, s'il y en a un. Notez que le système d'exploitation décide quel thread recevra celui-ci.

Remerciements

Merci à Thibaut Cuvelier pour la traduction ainsi qu'à Jonathan Courtois et Jacques Thery pour la relecture !