La classe CWinThread

Représente un thread d'exécution dans une application.

Syntaxe

class CWinThread : public CCmdTarget

Membres

Constructeurs publics

Nom	Description
CWinThread::CWinThread	Construit un objet CWinThread.

Méthodes publiques

Nom	Description
CWinThread::CreateThread	Démarre l’exécution d’un CWinThread objet.
CWinThread::ExitInstance	Remplacez le nettoyage lorsque votre thread se termine.
CWinThread::GetMainWnd	Récupère un pointeur vers la fenêtre principale du thread.
CWinThread::GetThreadPriority	Obtient la priorité du thread actuel.
CWinThread::InitInstance	Remplacer pour effectuer l’initialisation d’une instance de thread.
CWinThread::IsIdleMessage	Recherche des messages spéciaux.
CWinThread::OnIdle	Remplacez la commande pour effectuer un traitement au moment d’inactivité spécifique au thread.
CWinThread::PostThreadMessage	Publie un message vers un autre CWinThread objet.
CWinThread::PreTranslateMessage	Filtre les messages avant qu’ils ne soient distribués aux fonctions TranslateMessage Windows et DispatchMessage.
CWinThread::ProcessMessageFilter	Intercepte certains messages avant d’atteindre l’application.
CWinThread::ProcessWndProcException	Intercepte toutes les exceptions non gérées levées par le message et les gestionnaires de commandes du thread.
CWinThread::PumpMessage	Contient la boucle de message du thread.
CWinThread::ResumeThread	Décrémente le nombre de suspensions d’un thread.
CWinThread::Run	Fonction de contrôle pour les threads avec une pompe de messages. Remplacez pour personnaliser la boucle de message par défaut.
CWinThread::SetThreadPriority	Définit la priorité du thread actuel.
CWinThread::SuspendThread	Incrémente le nombre d’interruptions d’un thread.

Opérateurs publics

Nom	Description
CWinThread::operator HANDLE	Récupère le handle de l’objet CWinThread .

Membres de données publics

Nom	Description
CWinThread::m_bAutoDelete	Spécifie s’il faut détruire l’objet à l’arrêt du thread.
CWinThread::m_hThread	Gérez le thread actuel.
CWinThread::m_nThreadID	ID du thread actuel.
CWinThread::m_pActiveWnd	Pointeur vers la fenêtre principale de l’application conteneur lorsqu’un serveur OLE est actif.
CWinThread::m_pMainWnd	Contient un pointeur vers la fenêtre principale de l’application.

Notes

Le thread principal d’exécution est généralement fourni par un objet dérivé de CWinApp; CWinApp est dérivé de CWinThread. Les objets supplémentaires CWinThread autorisent plusieurs threads au sein d’une application donnée.

Il existe deux types généraux de threads qui CWinThread prennent en charge les threads de travail et les threads d’interface utilisateur. Les threads de travail n’ont aucune pompe de message : par exemple, un thread qui effectue des calculs en arrière-plan dans une application de feuille de calcul. Les threads d’interface utilisateur ont une pompe de messages et traitent les messages reçus du système. CWinApp et les classes dérivées sont des exemples de threads d’interface utilisateur. D’autres threads d’interface utilisateur peuvent également être dérivés directement de CWinThread.

Les objets de classe CWinThread existent généralement pendant la durée du thread. Si vous souhaitez modifier ce comportement, définissez sur m_bAutoDelete FALSE.

La CWinThread classe est nécessaire pour rendre votre code et MFC entièrement thread-safe. Les données locales de thread utilisées par l’infrastructure pour gérer les informations spécifiques aux threads sont gérées par CWinThread des objets. En raison de cette dépendance vis-à-vis CWinThread de la gestion des données locales de thread, tous les threads qui utilisent MFC doivent être créés par MFC. Par exemple, un thread créé par la fonction _beginthreadd’exécution ne _beginthreadex peut pas utiliser d’API MFC.

Pour créer un thread, appelez AfxBeginThread. Il existe deux formulaires, selon que vous souhaitez un thread de travail ou d’interface utilisateur. Si vous souhaitez un thread d’interface utilisateur, passez à AfxBeginThread un pointeur vers la CRuntimeClass classe dérivée de votre CWinThreadfichier. Si vous souhaitez créer un thread de travail, passez à un pointeur vers AfxBeginThread la fonction de contrôle et le paramètre à la fonction de contrôle. Pour les threads de travail et les threads d’interface utilisateur, vous pouvez spécifier des paramètres facultatifs qui modifient la priorité, la taille de la pile, les indicateurs de création et les attributs de sécurité. AfxBeginThread retourne un pointeur vers votre nouvel CWinThread objet.

Au lieu d’appeler AfxBeginThread, vous pouvez construire un CWinThreadobjet dérivé, puis appeler CreateThread. Cette méthode de construction en deux étapes est utile si vous souhaitez réutiliser l’objet CWinThread entre la création successive et les terminaisons des exécutions de threads.

Pour plus d’informations sur CWinThread, consultez les articles Multithreading avec C++ et MFC, Multithreading : Création de threads d’interface utilisateur, multithreading : création de threads de travail et multithreading : utilisation des classes de synchronisation.

Hiérarchie d'héritage

CObject

CCmdTarget

CWinThread

Spécifications

En-tête : afxwin.h

CWinThread::CreateThread

Crée un thread à exécuter dans l’espace d’adressage du processus appelant.

BOOL CreateThread(
    DWORD dwCreateFlags = 0,
    UINT nStackSize = 0,
    LPSECURITY_ATTRIBUTES lpSecurityAttrs = NULL);

Paramètres

dwCreateFlags
Spécifie un indicateur supplémentaire qui contrôle la création du thread. Cet indicateur peut contenir l’une des deux valeurs suivantes :

• CREATE_SUSPENDED Démarrez le thread avec un nombre d’interruptions d’un. Utilisez cette option CREATE_SUSPENDED si vous souhaitez initialiser des données membres de l’objet CWinThread , telles que m_bAutoDelete ou des membres de votre classe dérivée, avant que le thread ne commence à s’exécuter. Une fois votre initialisation terminée, utilisez le CWinThread::ResumeThread thread en cours d’exécution. Le thread n’est pas exécuté tant qu’il CWinThread::ResumeThread n’est pas appelé.

• 0 Démarrez le thread immédiatement après la création.

nStackSize
Spécifie la taille en octets de la pile pour le nouveau thread. Si 0, la taille de la pile est par défaut de la même taille que celle du thread principal du processus.

lpSecurityAttrs
Pointe vers une SECURITY_ATTRIBUTES structure qui spécifie les attributs de sécurité du thread.

Valeur de retour

Différent de zéro si le thread est créé avec succès ; sinon 0.

Notes

Permet AfxBeginThread de créer un objet thread et de l’exécuter en une seule étape. Utilisez cette option CreateThread si vous souhaitez réutiliser l’objet thread entre la création successive et l’arrêt des exécutions de threads.

CWinThread::CWinThread

Construit un objet CWinThread.

CWinThread();

Notes

Pour commencer l’exécution du thread, appelez la CreateThread fonction membre. Vous allez généralement créer des threads en appelant AfxBeginThread, ce qui appelle ce constructeur et CreateThread.

CWinThread::ExitInstance

Appelé par l’infrastructure à partir d’une fonction membre rarement substituée Run pour quitter cette instance du thread, ou si un appel échoue InitInstance .

virtual int ExitInstance();

Valeur de retour

Code de sortie du thread ; 0 indique aucune erreur et les valeurs supérieures à 0 indiquent une erreur. Cette valeur peut être récupérée en appelant GetExitCodeThread.

Notes

N’appelez pas cette fonction membre n’importe où, mais dans la Run fonction membre. Cette fonction membre est utilisée uniquement dans les threads d’interface utilisateur.

L’implémentation par défaut de cette fonction supprime l’objet CWinThread si m_bAutoDelete c’est TRUEle cas. Remplacez cette fonction si vous souhaitez effectuer un nettoyage supplémentaire lorsque votre thread se termine. Votre implémentation ExitInstance doit appeler la version de la classe de base après l’exécution de votre code.

CWinThread::GetMainWnd

Si votre application est un serveur OLE, appelez cette fonction pour récupérer un pointeur vers la fenêtre principale active de l’application au lieu de faire directement référence au m_pMainWnd membre de l’objet d’application.

virtual CWnd* GetMainWnd();

Valeur de retour

Cette fonction retourne un pointeur vers l’un des deux types de fenêtres. Si votre thread fait partie d’un serveur OLE et a un objet actif sur place à l’intérieur d’un conteneur actif, cette fonction retourne le CWinApp::m_pActiveWnd membre de données de l’objet CWinThread .

S’il n’existe aucun objet actif sur place dans un conteneur ou que votre application n’est pas un serveur OLE, cette fonction retourne le m_pMainWnd membre de données de votre objet thread.

Notes

Pour les threads d’interface utilisateur, cela équivaut directement à faire référence au m_pActiveWnd membre de votre objet d’application.

Si votre application n’est pas un serveur OLE, l’appel de cette fonction équivaut à faire directement référence au m_pMainWnd membre de votre objet d’application.

Remplacez cette fonction pour modifier le comportement par défaut.

CWinThread::GetThreadPriority

Obtient le niveau de priorité de thread actuel de ce thread.

int GetThreadPriority();

Valeur de retour

Niveau de priorité de thread actuel dans sa classe de priorité. La valeur retournée est l’une des valeurs suivantes, répertoriées de priorité la plus élevée à la plus basse :

• THREAD_PRIORITY_TIME_CRITICAL

• THREAD_PRIORITY_HIGHEST

• THREAD_PRIORITY_ABOVE_NORMAL

• THREAD_PRIORITY_NORMAL

• THREAD_PRIORITY_BELOW_NORMAL

• THREAD_PRIORITY_LOWEST

• THREAD_PRIORITY_IDLE

Pour plus d’informations sur ces priorités, consultez SetThreadPriority le Kit de développement logiciel (SDK) Windows.

CWinThread::InitInstance

InitInstance doit être substitué pour initialiser chaque nouvelle instance d’un thread d’interface utilisateur.

virtual BOOL InitInstance();

Valeur de retour

Différent de zéro si l’initialisation réussit ; sinon 0.

Notes

En règle générale, vous remplacez InitInstance pour effectuer des tâches qui doivent être effectuées lors de la création d’un thread.

Cette fonction membre est utilisée uniquement dans les threads d’interface utilisateur. Effectuer l’initialisation des threads de travail dans la fonction de contrôle passée à AfxBeginThread.

CWinThread::IsIdleMessage

Remplacez cette fonction pour empêcher OnIdle l’appel après la génération de messages spécifiques.

virtual BOOL IsIdleMessage(MSG* pMsg);

Paramètres

pMsg
Pointe vers le message actuel en cours de traitement.

Valeur de retour

Différent de zéro s’il OnIdle doit être appelé après le traitement du message ; sinon, 0.

Notes

L’implémentation par défaut n’appelle OnIdle pas après les messages et messages redondants générés par des carets clignotants.

Si une application a créé un minuteur court, OnIdle elle est appelée fréquemment, ce qui provoque des problèmes de performances. Pour améliorer les performances d’une telle application, remplacez-les IsIdleMessage dans la classe dérivée de CWinAppl’application pour rechercher WM_TIMER les messages comme suit :

BOOL CMyWinApp::IsIdleMessage(MSG* pMsg)
{
   if (!CWinApp::IsIdleMessage(pMsg) || pMsg->message == WM_TIMER)
      return FALSE;
   else
      return TRUE;
}

La gestion WM_TIMER de cette façon améliore les performances des applications qui utilisent des minuteurs courts.

CWinThread::m_bAutoDelete

Spécifie si l’objet doit être supprimé automatiquement à l’arrêt CWinThread du thread.

BOOL m_bAutoDelete;

Notes

Le m_bAutoDelete membre de données est une variable publique de type BOOL.

La valeur de m_bAutoDelete n’affecte pas la façon dont le handle de thread sous-jacent est fermé, mais il affecte le minutage de la fermeture du handle. Le handle de thread est toujours fermé lorsque l’objet CWinThread est détruit.

CWinThread::m_hThread

Handle to the thread attached to this CWinThread.

HANDLE m_hThread;

Notes

Le m_hThread membre de données est une variable publique de type HANDLE. Il n’est valide que si l’objet thread du noyau sous-jacent existe actuellement et que le handle n’a pas encore été fermé.

Le CWinThread destructeur appelle CloseHandle le m_hThread. Si m_bAutoDelete c’est TRUE le cas lorsque le thread se termine, l’objet CWinThread est détruit, ce qui invalide tous les pointeurs vers l’objet CWinThread et ses variables membres. Vous devrez peut-être que le m_hThread membre vérifie la valeur de sortie du thread ou attend un signal. Pour conserver l’objet et son m_hThread membre pendant l’exécution CWinThread du thread et après son arrêt, définissez-le m_bAutoDelete FALSE avant d’autoriser l’exécution du thread à continuer. Sinon, le thread peut se terminer, détruire l’objet CWinThread et fermer le handle avant de tenter de l’utiliser. Si vous utilisez cette technique, vous êtes responsable de la suppression de l’objet CWinThread .

CWinThread::m_nThreadID

ID du thread attaché à ce CWinThread.

DWORD m_nThreadID;

Notes

Le m_nThreadID membre de données est une variable publique de type DWORD. Il n’est valide que si l’objet thread du noyau sous-jacent existe actuellement. Consultez également les remarques sur m_hThread la durée de vie.

Exemple

Consultez l’exemple pour AfxGetThread.

CWinThread::m_pActiveWnd

Utilisez ce membre de données pour stocker un pointeur vers l’objet de fenêtre active de votre thread.

CWnd* m_pActiveWnd;

Notes

La bibliothèque de classes Microsoft Foundation met automatiquement fin à votre thread lorsque la fenêtre référencée par m_pActiveWnd est fermée. Si ce thread est le thread principal d’une application, l’application est également arrêtée. Si ce membre de données est NULL, la fenêtre active de l’objet de CWinApp l’application est héritée. m_pActiveWnd est une variable publique de type CWnd*.

En règle générale, vous définissez cette variable membre lorsque vous remplacez InitInstance. Dans un thread de travail, la valeur de ce membre de données est héritée de son thread parent.

CWinThread::m_pMainWnd

Utilisez ce membre de données pour stocker un pointeur vers l’objet de fenêtre principale de votre thread.

CWnd* m_pMainWnd;

Notes

La bibliothèque de classes Microsoft Foundation met automatiquement fin à votre thread lorsque la fenêtre référencée par m_pMainWnd est fermée. Si ce thread est le thread principal d’une application, l’application est également arrêtée. Si ce membre de données est NULL, la fenêtre principale de l’objet de CWinApp l’application est utilisée pour déterminer quand arrêter le thread. m_pMainWnd est une variable publique de type CWnd*.

En règle générale, vous définissez cette variable membre lorsque vous remplacez InitInstance. Dans un thread de travail, la valeur de ce membre de données est héritée de son thread parent.

CWinThread::OnIdle

Remplacez cette fonction membre pour effectuer un traitement en temps d’inactivité.

virtual BOOL OnIdle(LONG lCount);

Paramètres

lCount
Un compteur incrémenté chaque fois OnIdle qu’il est appelé lorsque la file d’attente de messages du thread est vide. Ce nombre est réinitialisé à 0 chaque fois qu’un nouveau message est traité. Vous pouvez utiliser le lCount paramètre pour déterminer la durée relative pendant laquelle le thread a été inactif sans traiter un message.

Valeur de retour

Non différent de zéro pour recevoir plus de temps de traitement inactif ; 0 si aucun temps de traitement inactif n’est nécessaire.

Notes

OnIdle est appelé dans la boucle de message par défaut lorsque la file d’attente de messages du thread est vide. Utilisez votre remplacement pour appeler vos propres tâches de gestionnaire inactif en arrière-plan.

OnIdle doit retourner 0 pour indiquer qu’aucune durée de traitement d’inactivité supplémentaire n’est nécessaire. Le lCount paramètre est incrémenté chaque fois OnIdle qu’il est appelé lorsque la file d’attente de messages est vide et qu’elle est réinitialisée à 0 chaque fois qu’un nouveau message est traité. Vous pouvez appeler vos différentes routines inactives en fonction de ce nombre.

L’implémentation par défaut de cette fonction membre libère les objets temporaires et les bibliothèques de liens dynamiques inutilisées de la mémoire.

Cette fonction membre est utilisée uniquement dans les threads d’interface utilisateur.

Étant donné que l’application ne peut pas traiter les messages tant qu’elle OnIdle n’est pas retournée, n’effectuez pas de longues tâches dans cette fonction.

CWinThread::operator HANDLE

Récupère le handle de l’objet CWinThread .

operator HANDLE() const;

Valeur de retour

En cas de réussite, handle de l’objet thread ; sinon, NULL.

Notes

Utilisez le handle pour appeler directement les API Windows.

CWinThread::PostThreadMessage

Appelé pour publier un message défini par l’utilisateur vers un autre CWinThread objet.

BOOL PostThreadMessage(
    UINT message,
    WPARAM wParam,
    LPARAM lParam);

Paramètres

message
ID du message défini par l’utilisateur.

wParam
Premier paramètre de message.

lParam
Deuxième paramètre de message.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0.

Notes

Le message publié est mappé au gestionnaire de messages approprié par la macro ON_THREAD_MESSAGEde mappage de messages.

CWinThread::PreTranslateMessage

Remplacez cette fonction pour filtrer les messages de fenêtre avant qu’ils ne soient distribués aux fonctions TranslateMessage Windows et DispatchMessage.

virtual BOOL PreTranslateMessage(MSG* pMsg);

Paramètres

pMsg
Pointe vers une MSG structure contenant le message à traiter.

Valeur de retour

Différent de zéro si le message a été entièrement traité PreTranslateMessage et ne doit pas être traité plus loin. Zéro si le message doit être traité de la manière normale.

Notes

Cette fonction membre est utilisée uniquement dans les threads d’interface utilisateur.

CWinThread::ProcessMessageFilter

La fonction de hook de l’infrastructure appelle cette fonction membre pour filtrer et répondre à certains messages Windows.

virtual BOOL ProcessMessageFilter(
    int code,
    LPMSG lpMsg);

Paramètres

code
Spécifie un code de hook. Cette fonction membre utilise le code pour déterminer comment traiter lpMsg.

lpMsg
Pointeur vers une structure WindowsMSG.

Valeur de retour

Différent de zéro si le message est traité ; sinon 0.

Notes

Une fonction de hook traite les événements avant qu’ils ne soient envoyés au traitement normal des messages de l’application.

Si vous remplacez cette fonctionnalité avancée, veillez à appeler la version de classe de base pour maintenir le traitement de hook de l’infrastructure.

CWinThread::ProcessWndProcException

L’infrastructure appelle cette fonction membre chaque fois que le gestionnaire n’intercepte pas d’exception levée dans l’un des gestionnaires de messages ou de commandes de votre thread.

virtual LRESULT ProcessWndProcException(
    CException* e,
    const MSG* pMsg);

Paramètres

e
Pointe vers une exception non gérée.

pMsg
Pointe vers une MSG structure contenant des informations sur le message Windows qui a provoqué la levée d’une exception par l’infrastructure.

Valeur de retour

-1 si une WM_CREATE exception est générée ; sinon, 0.

Notes

N’appelez pas directement cette fonction membre.

L’implémentation par défaut de cette fonction membre gère uniquement les exceptions générées à partir des messages suivants :

Commande	Action
WM_CREATE	Échouer.
WM_PAINT	Validez la fenêtre affectée, ce qui empêche la génération d’un autre WM_PAINT message.

Remplacez cette fonction membre pour fournir une gestion globale de vos exceptions. Appelez la fonctionnalité de base uniquement si vous souhaitez afficher le comportement par défaut.

Cette fonction membre est utilisée uniquement dans les threads qui ont une pompe de message.

CWinThread::PumpMessage

Contient la boucle de message du thread.

virtual BOOL PumpMessage();

Notes

PumpMessage contient la boucle de message du thread. PumpMessage est appelé par CWinThread le fait de pomper les messages du thread. Vous pouvez appeler PumpMessage directement pour forcer le traitement des messages, ou vous pouvez remplacer PumpMessage pour modifier son comportement par défaut.

L’appel PumpMessage directement et la substitution de son comportement par défaut est recommandé uniquement pour les utilisateurs avancés.

CWinThread::ResumeThread

Appelé pour reprendre l’exécution d’un thread suspendu par la SuspendThread fonction membre ou un thread créé avec l’indicateur CREATE_SUSPENDED .

DWORD ResumeThread();

Valeur de retour

Nombre de suspensions précédents du thread en cas de réussite ; 0xFFFFFFFF autrement. Si la valeur de retour est égale à zéro, le thread actuel n’a pas été suspendu. Si la valeur de retour est une valeur, le thread a été suspendu, mais est maintenant redémarré. Toute valeur de retour supérieure à une signifie que le thread reste suspendu.

Notes

Le nombre de suspensions du thread actuel est réduit d’un. Si le nombre de suspensions est réduit à zéro, le thread reprend l’exécution ; sinon, le thread reste suspendu.

CWinThread::Run

Fournit une boucle de message par défaut pour les threads d’interface utilisateur.

virtual int Run();

Valeur de retour

Valeur int retournée par le thread. Cette valeur peut être récupérée en appelant GetExitCodeThread.

Notes

Run acquiert et distribue des messages Windows jusqu’à ce que l’application reçoive un WM_QUIT message. Si la file d’attente de messages du thread ne contient actuellement aucun message, Run les appels OnIdle pour effectuer un traitement en temps d’inactivité. Les messages entrants vont à la PreTranslateMessage fonction membre pour un traitement spécial, puis à la fonction TranslateMessage Windows pour la traduction de clavier standard. Enfin, la DispatchMessage fonction Windows est appelée.

Run est rarement substitué, mais vous pouvez le remplacer pour implémenter un comportement spécial.

Cette fonction membre est utilisée uniquement dans les threads d’interface utilisateur.

CWinThread::SetThreadPriority

Cette fonction définit le niveau de priorité du thread actuel dans sa classe de priorité.

BOOL SetThreadPriority(int nPriority);

Paramètres

nPriority
Spécifie le nouveau niveau de priorité de thread dans sa classe de priorité. Ce paramètre doit être l’une des valeurs suivantes, répertoriées entre la priorité la plus élevée et la plus basse :

• THREAD_PRIORITY_TIME_CRITICAL

• THREAD_PRIORITY_HIGHEST

• THREAD_PRIORITY_ABOVE_NORMAL

• THREAD_PRIORITY_NORMAL

• THREAD_PRIORITY_BELOW_NORMAL

• THREAD_PRIORITY_LOWEST

• THREAD_PRIORITY_IDLE

Pour plus d’informations sur ces priorités, consultez SetThreadPriority le Kit de développement logiciel (SDK) Windows.

Valeur de retour

Différent de zéro si la fonction a réussi ; sinon 0.

Notes

Elle ne peut être appelée qu’après CreateThread avoir réussi à retourner.

CWinThread::SuspendThread

Incrémente le nombre de suspensions du thread actuel.

DWORD SuspendThread();

Valeur de retour

Nombre de suspensions précédents du thread en cas de réussite ; 0xFFFFFFFF autrement.

Notes

Si un thread a un nombre d’interruptions supérieur à zéro, ce thread ne s’exécute pas. Le thread peut être repris en appelant la ResumeThread fonction membre.

Voir aussi

CCmdTarget Classe
Graphique hiérarchique
CWinApp Classe
CCmdTarget Classe