===== QThread ===== La classe QThread fournit des threads indépendants de la plateforme. [[#Description détaillée|Plus d'informations...]] ==== 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 [[qthread#run|run()]]. Par défaut, [[qthread#run|run()]] démarre la boucle événementielle en appelant [[qthread#exec|exec()]] (voir ci-après). Pour créer vos propres threads, dérivez de QThread et réimplémentez [[qthread#run|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 [[qthread#start|start()]] pour commencer l'exécution, qui finit quand vous retournez depuis [[qthread#run|run()]], exactement comme une application fait quand elle quitte ''main()''. QThread vous préviendra //via// un signal quand le thread est [[qthread#started|lancé]], [[qthread#finished|fini]] et [[qthread#terminated|terminé]] ; alternativement, vous pouvez utiliser [[qthread#isFinished|isFinished()]] et [[qthread#isRunning|isRunning()]] pour demander l'état du thread. Utilisez [[qthread#wait|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 [[qthread#setStackSize|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 [[qthread#exec|exec()]] et l'arrêter avec [[qthread#exit|exit()]] ou [[qthread#quit|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é [[qt#ConnectionType-enum|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 [[qthread#terminate|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 [[qthread#terminate|terminate()]] et de [[qthread#setTerminationEnabled|setTerminationEnabled()]] pour plus d'informations. Les fonctions statiques [[qthread#currentThreadId|currentThreadId()]] et [[qthread#currentThread|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 [[qthread#sleep|sleep()]] pour une précision à la seconde, [[qthread#msleep|msleep()]] à la milliseconde et [[qthread#usleep|usleep()]] à la microseconde. Voir aussi [[threads|Le support des threads dans Qt]], [[QThreadStorage]], [[QMutex]], [[QSemaphore]], [[QWaitCondition]], [[threads-mandelbrot|l'exemple Mandelbrot]], [[threads-semaphores|l'exemple Semaphores]] et [[threads-waitconditions|l'exemple Wait Conditions]]. ==== Type ==== === Priority-enum === ''enum QThread::Priority'' Cette énumération indique la manière dont le système d'exploitation devrait programmer les threads nouvellement créés. ^ Constante ^ Valeur ^ Description ^ | ''QThread::IdlePriority'' | ''0'' | Programmé seulement quand aucun autre thread n'est lancé. | | ''QThread::LowestPriority'' | ''1'' | Programmé moins souvent que ''LowPriority''. | | ''QThread::LowPriority'' | ''2'' | Programmé moins souvent que ''NormalPriority''. | | ''QThread::NormalPriority'' | ''3'' | La priorité par défaut du système d'exploitation. | | ''QThread::HighPriority'' | ''4'' | Programmé plus souvent que ''NormalPriority''. | | ''QThread::HighestPriority'' | ''5'' | Programmé plus souvent que ''HighPriority''. | | ''QThread::TimeCriticalPriority'' | ''6'' | Programmé aussi souvent que possible. | | ''QThread::InheritPriority'' | ''7'' | Utiliser la même priorité que le thread créateur. Ceci est la valeur par défaut. | ==== Fonctions membres ==== === QThread() === ''QThread::QThread ( [[QObject]] * parent = 0 )'' Construit un nouveau thread avec le parent donné. Le thread n'est pas exécuté tant que la fonction [[qthread#start|start()]] n'a pas été appelée. Voir aussi [[qthread#start|start()]]. === ~QThread() === ''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 [[qthread#isFinished|isFinished()]] retourne ''false'') va probablement crasher le programme. Vous pouvez [[qthread#wait|attendre]] un thread pour vous assurer qu'il a terminé. === currentThread() === ''QThread * QThread::currentThread () [static]'' Retourne un pointeur sur un [[QThread]] qui représente le thread en cours d'exécution. === currentThreadId() === ''[[qt#HANDLE-typedef|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()''. === exec() === ''int QThread::exec () [protected]'' Entre dans la boucle événementielle et attend jusqu'à ce que [[qthread#exit|exit()]] soit appelé, retournant la valeur passée à [[qthread#exit|exit()]]. La valeur retournée est 0 si [[qthread#exit|exit()]] est appelé //via// [[qthread#quit|quit()]]. Il est nécessaire d'appeler cette fonction pour démarrer la gestion des événements. Voir aussi [[qthread#quit|quit()]] et [[qthread#exit|exit()]]. === 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|QEventLoop::exec()]]. La fonction [[qeventloop#exec|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 [[qthread#quit|quit()]] et [[QEventLoop]]. === finished() === ''void QThread::finished () [signal]'' Ce signal est émis quand le thread a fini son exécution. Voir aussi [[qthread#started|started()]] et [[qthread#terminated|terminated()]]. === idealThreadCount() === ''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é. === isFinished() === ''bool QThread::isFinished () const'' Retourne ''true'' si le thread a terminé son exécution, ''false'' sinon. Voir aussi [[qthread#isRunning|isRunning()]]. === isRunning() === ''bool QThread::isRunning () const'' Retourne ''true'' si le thread est en cours d'exécution, ''false'' sinon. Voir aussi [[qthread#isFinished|isFinished()]]. === msleep() === ''void QThread::msleep ( unsigned long msecs ) [static protected]'' Le thread actuel attendra ''msecs'' millisecondes. Voir aussi [[qthread#sleep|sleep()]] et [[qthread#usleep|usleep()]]. === priority() === ''[[qthread#Priority-enum|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 [[qthread#Priority-enum|Priority]], [[qthread#setPriority|setPriority()]] et [[qthread#start|start()]]. === quit() === ''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 à ''[[#exit()|QThread::exit]](0)''. Cette fonction ne fait rien s'il n'y a pas de boucle événementielle. Voir aussi [[qthread#exit|exit()]] et [[QEventLoop]]. === run() === ''void QThread::run () [virtual protected]'' Le point d'entrée du thread. Après l'appel à [[qthread#start|start()]], le thread nouvellement créé appelle cette fonction. L'implémentation par défaut appelle simplement [[qthread#exec|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 [[qthread#start|start()]] et [[qthread#wait|wait()]]. === setPriority() === ''void QThread::setPriority ( [[qthread#Priority-enum|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 [[qthread#start|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 [[qthread#Priority-enum|Priority]], [[qthread#priority|priority()]] et [[qthread#start|start()]]. === setStackSize() === ''void QThread::setStackSize ( [[qtglobal#uint-typedef|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 [[qthread#stackSize|stackSize()]]. === setTerminationEnabled() === ''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|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|QThread::terminate()]] termineront le thread normalement. Si une interruption a été différée (c'est-à-dire si [[qthread#terminate|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 [[qthread#terminate|terminate()]]. === sleep() === ''void QThread::sleep ( unsigned long secs ) [static protected]'' Force le thread actuel à dormir pendant ''secs'' secondes. Voir aussi [[qthread#msleep|msleep()]] et [[qthread#usleep|usleep()]]. === stackSize() === ''[[qtglobal#uint-typedef|uint]] QThread::stackSize () const'' Retourne la taille maximale de la pile du thread si elle a été définie avec [[qthread#setStackSize|setStackSize()]], sinon retourne 0. Voir aussi [[qthread#setStackSize|setStackSize()]]. === start() === ''void QThread::start ( [[qthread#Priority-enum|Priority]] priority = InheritPriority ) [slot]'' Débute l'exécution du thread en appelant [[qthread#run|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 [[qthread#run|run()]] et [[qthread#terminate|terminate()]]. === started() === ''void QThread::started () [signal]'' Ce signal est émis quand le thread commence son exécution. Voir aussi [[qthread#finished|finished()]] et [[qthread#terminated|terminated()]]. === terminate() === ''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|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|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|QThread::setTerminationEnabled()]] pour plus d'informations. Voir aussi [[qthread#setTerminationEnabled|setTerminationEnabled()]]. === terminated() === ''void QThread::terminated () [signal]'' Ce signal est émis quand le thread est interrompu. Voir aussi [[qthread#started|started()]] et [[qthread#finished|finished()]]. === usleep() === ''void QThread::usleep ( unsigned long usecs ) [static protected]'' Fait en sorte que le thread actuel dorme pour ''usecs'' microsecondes. Voir aussi [[qthread#sleep|sleep()]] et [[qthread#msleep|msleep()]]. === wait() === ''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 [[qthread#run|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 [[qthread#run|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 [[qthread#sleep|sleep()]] et [[qthread#terminate|terminate()]]. === yieldCurrentThread() === ''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 à pour la traduction ainsi qu'à et pour la relecture !