Classe CWinThread

Rappresenta un thread di esecuzione all'interno di un'applicazione.

Sintassi

class CWinThread : public CCmdTarget

Membri

Costruttori pubblici

Nome	Descrizione
CWinThread::CWinThread	Costruisce un oggetto CWinThread.

Metodi pubblici

Nome	Descrizione
CWinThread::CreateThread	Avvia l'esecuzione di un CWinThread oggetto .
CWinThread::ExitInstance	Eseguire l'override per eseguire la pulizia al termine del thread.
CWinThread::GetMainWnd	Recupera un puntatore alla finestra principale per il thread.
CWinThread::GetThreadPriority	Ottiene la priorità del thread corrente.
CWinThread::InitInstance	Eseguire l'override per eseguire l'inizializzazione dell'istanza del thread.
CWinThread::IsIdleMessage	Verifica la presenza di messaggi speciali.
CWinThread::OnIdle	Eseguire l'override per eseguire l'elaborazione inattiva specifica del thread.
CWinThread::PostThreadMessage	Invia un messaggio a un altro CWinThread oggetto.
CWinThread::PreTranslateMessage	Filtra i messaggi prima che vengano inviati alle funzioni TranslateMessage di Windows e DispatchMessage.
CWinThread::ProcessMessageFilter	Intercetta determinati messaggi prima di raggiungere l'applicazione.
CWinThread::ProcessWndProcException	Intercetta tutte le eccezioni non gestite generate dai gestori di messaggi e comandi del thread.
CWinThread::PumpMessage	Contiene il ciclo di messaggi del thread.
CWinThread::ResumeThread	Decrementa il numero di sospensioni di un thread.
CWinThread::Run	Funzione di controllo per i thread con un message pump. Eseguire l'override per personalizzare il ciclo di messaggi predefinito.
CWinThread::SetThreadPriority	Imposta la priorità del thread corrente.
CWinThread::SuspendThread	Incrementa il numero di sospensioni di un thread.

Operatori pubblici

Nome	Descrizione
CWinThread::operator HANDLE	Recupera l'handle dell'oggetto CWinThread .

Membri dati pubblici

Nome	Descrizione
CWinThread::m_bAutoDelete	Specifica se eliminare definitivamente l'oggetto alla terminazione del thread.
CWinThread::m_hThread	Handle per il thread corrente.
CWinThread::m_nThreadID	ID del thread corrente.
CWinThread::m_pActiveWnd	Puntatore alla finestra principale dell'applicazione contenitore quando un server OLE è attivo sul posto.
CWinThread::m_pMainWnd	Contiene un puntatore alla finestra principale dell'applicazione.

Osservazioni:

Il thread principale di esecuzione viene in genere fornito da un oggetto derivato da CWinApp; CWinApp è derivato da CWinThread. Gli oggetti aggiuntivi CWinThread consentono più thread all'interno di una determinata applicazione.

Esistono due tipi generali di thread che CWinThread supportano: thread di lavoro e thread dell'interfaccia utente. I thread di lavoro non dispongono di message pump: ad esempio, un thread che esegue calcoli in background in un'applicazione foglio di calcolo. I thread dell'interfaccia utente hanno un message pump ed elaborano i messaggi ricevuti dal sistema. CWinApp e le classi derivate da esso sono esempi di thread dell'interfaccia utente. Anche altri thread dell'interfaccia utente possono essere derivati direttamente da CWinThread.

Gli oggetti della classe CWinThread in genere esistono per la durata del thread. Se si desidera modificare questo comportamento, impostare su m_bAutoDelete FALSE.

La CWinThread classe è necessaria per rendere il codice e MFC completamente thread-safe. I dati locali del thread usati dal framework per gestire informazioni specifiche del thread vengono gestiti dagli CWinThread oggetti . A causa di questa dipendenza da CWinThread gestire i dati locali del thread, qualsiasi thread che usa MFC deve essere creato da MFC. Ad esempio, un thread creato dalla funzione _beginthreaddi runtime , _beginthreadex non può usare api MFC.

Per creare un thread, chiamare AfxBeginThread. Esistono due moduli, a seconda che si desideri un thread di lavoro o di interfaccia utente. Se si vuole un thread dell'interfaccia utente, passare a AfxBeginThread un puntatore alla CRuntimeClass classe CWinThreadderivata da . Se si vuole creare un thread di lavoro, passare a AfxBeginThread un puntatore alla funzione di controllo e al parametro alla funzione di controllo. Sia per i thread di lavoro che per i thread dell'interfaccia utente, è possibile specificare parametri facoltativi che modificano priorità, dimensioni dello stack, flag di creazione e attributi di sicurezza. AfxBeginThread restituirà un puntatore al nuovo CWinThread oggetto.

Anziché chiamare AfxBeginThread, è possibile costruire un CWinThreadoggetto derivato da e quindi chiamare CreateThread. Questo metodo di costruzione a due fasi è utile se si desidera riutilizzare l'oggetto CWinThread tra la creazione successiva e la terminazione delle esecuzioni di thread.

Per altre informazioni su CWinThread, vedere gli articoli Multithreading con C++ e MFC, Multithreading: Creazione di thread dell'interfaccia utente, multithreading: creazione di thread di lavoro e multithreading: Come usare le classi di sincronizzazione.

Gerarchia di ereditarietà

CObject

CCmdTarget

CWinThread

Requisiti

Intestazione: afxwin.h

CWinThread::CreateThread

Crea un thread da eseguire all'interno dello spazio indirizzi del processo chiamante.

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

Parametri

dwCreateFlags
Specifica un flag aggiuntivo che controlla la creazione del thread. Questo flag può contenere uno dei due valori seguenti:

• CREATE_SUSPENDED Avviare il thread con un conteggio di sospensione di uno. Utilizzare CREATE_SUSPENDED se si desidera inizializzare i dati dei membri dell'oggetto CWinThread , ad esempio m_bAutoDelete o qualsiasi membro della classe derivata, prima che il thread inizi l'esecuzione. Al termine dell'inizializzazione, usare per CWinThread::ResumeThread avviare il thread in esecuzione. Il thread non verrà eseguito fino a quando CWinThread::ResumeThread non viene chiamato .

• 0 Avviare il thread immediatamente dopo la creazione.

nStackSize
Specifica le dimensioni in byte dello stack per il nuovo thread. Se 0, per impostazione predefinita le dimensioni dello stack sono uguali a quella del thread primario del processo.

lpSecurityAttrs
Punta a una SECURITY_ATTRIBUTES struttura che specifica gli attributi di sicurezza per il thread.

Valore restituito

Diverso da zero se il thread viene creato correttamente; in caso contrario, 0.

Osservazioni:

Usare AfxBeginThread per creare un oggetto thread ed eseguirlo in un unico passaggio. Usare CreateThread se si desidera riutilizzare l'oggetto thread tra la creazione successiva e la terminazione delle esecuzioni di thread.

CWinThread::CWinThread

Costruisce un oggetto CWinThread.

CWinThread();

Osservazioni:

Per avviare l'esecuzione del thread, chiamare la CreateThread funzione membro. In genere si creeranno thread chiamando AfxBeginThread, che chiamerà questo costruttore e CreateThread.

CWinThread::ExitInstance

Chiamato dal framework dall'interno di una funzione membro raramente sottoposta a override Run per uscire da questa istanza del thread o se una chiamata a InitInstance non riesce.

virtual int ExitInstance();

Valore restituito

Codice di uscita del thread; 0 indica che non sono presenti errori e i valori maggiori di 0 indicano un errore. Questo valore può essere recuperato chiamando GetExitCodeThread.

Osservazioni:

Non chiamare questa funzione membro da qualsiasi posizione, ma all'interno della Run funzione membro. Questa funzione membro viene usata solo nei thread dell'interfaccia utente.

L'implementazione predefinita di questa funzione elimina l'oggetto CWinThread se m_bAutoDelete è TRUE. Eseguire l'override di questa funzione se si desidera eseguire operazioni di pulizia aggiuntive al termine del thread. L'implementazione di ExitInstance deve chiamare la versione della classe di base dopo l'esecuzione del codice.

CWinThread::GetMainWnd

Se l'applicazione è un server OLE, chiamare questa funzione per recuperare un puntatore alla finestra principale attiva dell'applicazione anziché fare riferimento direttamente al m_pMainWnd membro dell'oggetto applicazione.

virtual CWnd* GetMainWnd();

Valore restituito

Questa funzione restituisce un puntatore a uno dei due tipi di finestre. Se il thread fa parte di un server OLE e ha un oggetto attivo sul posto all'interno di un contenitore attivo, questa funzione restituisce il CWinApp::m_pActiveWnd membro dati dell'oggetto CWinThread .

Se non è presente alcun oggetto attivo sul posto all'interno di un contenitore o l'applicazione non è un server OLE, questa funzione restituisce il m_pMainWnd membro dati dell'oggetto thread.

Osservazioni:

Per i thread dell'interfaccia utente, equivale a fare riferimento direttamente al m_pActiveWnd membro dell'oggetto applicazione.

Se l'applicazione non è un server OLE, chiamare questa funzione equivale a fare riferimento direttamente al membro m_pMainWnd dell'oggetto applicazione.

Eseguire l'override di questa funzione per modificare il comportamento predefinito.

CWinThread::GetThreadPriority

Ottiene il livello di priorità del thread corrente di questo thread.

int GetThreadPriority();

Valore restituito

Livello di priorità del thread corrente all'interno della relativa classe di priorità. Il valore restituito sarà uno dei seguenti, elencati dalla priorità più alta al più basso:

• THREAD_PRIORITY_TIME_CRITICAL

• THREAD_PRIORITY_HIGHEST

• THREAD_PRIORITY_ABOVE_NORMAL

• THREAD_PRIORITY_NORMAL

• THREAD_PRIORITY_BELOW_NORMAL

• THREAD_PRIORITY_LOWEST

• THREAD_PRIORITY_IDLE

Per altre informazioni su queste priorità, vedere SetThreadPriority in Windows SDK.

CWinThread::InitInstance

InitInstance deve essere sottoposto a override per inizializzare ogni nuova istanza di un thread dell'interfaccia utente.

virtual BOOL InitInstance();

Valore restituito

Diverso da zero se l'inizializzazione ha esito positivo; in caso contrario, 0.

Osservazioni:

In genere, si esegue l'override InitInstance per eseguire attività che devono essere completate al momento della creazione di un thread.

Questa funzione membro viene usata solo nei thread dell'interfaccia utente. Eseguire l'inizializzazione dei thread di lavoro nella funzione di controllo passata a AfxBeginThread.

CWinThread::IsIdleMessage

Eseguire l'override di questa funzione per evitare OnIdle che venga chiamato dopo la generazione di messaggi specifici.

virtual BOOL IsIdleMessage(MSG* pMsg);

Parametri

pMsg
Punta al messaggio corrente in fase di elaborazione.

Valore restituito

Diverso da zero se OnIdle deve essere chiamato dopo l'elaborazione del messaggio; in caso contrario, 0.

Osservazioni:

L'implementazione predefinita non chiama OnIdle dopo i messaggi del mouse ridondanti e i messaggi generati da punti di inserimento lampeggianti.

Se un'applicazione ha creato un breve timer, OnIdle verrà chiamata frequentemente, causando problemi di prestazioni. Per migliorare le prestazioni di un'applicazione di questo tipo, eseguire l'override IsIdleMessage nella classe derivata dall'applicazione per verificare la presenza WM_TIMER di CWinAppmessaggi nel modo seguente:

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

La gestione WM_TIMER in questo modo migliorerà le prestazioni delle applicazioni che usano timer brevi.

CWinThread::m_bAutoDelete

Specifica se l'oggetto CWinThread deve essere eliminato automaticamente alla chiusura del thread.

BOOL m_bAutoDelete;

Osservazioni:

Il m_bAutoDelete membro dati è una variabile pubblica di tipo BOOL.

Il valore di non influisce sulla modalità di m_bAutoDelete chiusura dell'handle di thread sottostante, ma influisce sulla tempistica di chiusura dell'handle. L'handle dei thread viene sempre chiuso quando l'oggetto CWinThread viene eliminato definitivamente.

CWinThread::m_hThread

Handle per il thread collegato a questo CWinThreadoggetto .

HANDLE m_hThread;

Osservazioni:

Il m_hThread membro dati è una variabile pubblica di tipo HANDLE. È valido solo se l'oggetto thread del kernel sottostante esiste e l'handle non è ancora stato chiuso.

Il CWinThread distruttore chiama CloseHandle su m_hThread. Se m_bAutoDelete è TRUE quando termina il thread, l'oggetto CWinThread viene eliminato definitivamente, che invalida eventuali puntatori all'oggetto CWinThread e alle relative variabili membro. Potrebbe essere necessario il m_hThread membro per controllare il valore di uscita del thread o per attendere un segnale. Per mantenere l'oggetto e il relativo m_hThread membro durante l'esecuzione CWinThread del thread e dopo l'interruzione, impostare su m_bAutoDelete FALSE prima di consentire l'esecuzione del thread per continuare. In caso contrario, il thread può terminare, distruggere l'oggetto CWinThread e chiudere l'handle prima di provare a usarlo. Se si utilizza questa tecnica, l'utente è responsabile dell'eliminazione dell'oggetto CWinThread .

CWinThread::m_nThreadID

ID del thread collegato a questo CWinThreadoggetto .

DWORD m_nThreadID;

Osservazioni:

Il m_nThreadID membro dati è una variabile pubblica di tipo DWORD. È valido solo se l'oggetto thread del kernel sottostante esiste attualmente. Vedere anche le osservazioni sulla m_hThread durata.

Esempio

Vedere l'esempio per AfxGetThread.

CWinThread::m_pActiveWnd

Usare questo membro dati per archiviare un puntatore all'oggetto finestra attiva del thread.

CWnd* m_pActiveWnd;

Osservazioni:

La libreria di classi di Microsoft Foundation terminerà automaticamente il thread quando la finestra a m_pActiveWnd cui fa riferimento viene chiusa. Se questo thread è il thread primario per un'applicazione, l'applicazione verrà terminata anche. Se questo membro dati è NULL, la finestra attiva per l'oggetto dell'applicazione CWinApp verrà ereditata. m_pActiveWnd è una variabile pubblica di tipo CWnd*.

In genere, si imposta questa variabile membro quando si esegue l'override di InitInstance. In un thread di lavoro il valore di questo membro dati viene ereditato dal thread padre.

CWinThread::m_pMainWnd

Usare questo membro dati per archiviare un puntatore all'oggetto finestra principale del thread.

CWnd* m_pMainWnd;

Osservazioni:

La libreria di classi di Microsoft Foundation terminerà automaticamente il thread quando la finestra a m_pMainWnd cui fa riferimento viene chiusa. Se questo thread è il thread primario per un'applicazione, l'applicazione verrà terminata anche. Se questo membro dati è NULL, verrà usata la finestra principale per l'oggetto dell'applicazione CWinApp per determinare quando terminare il thread. m_pMainWnd è una variabile pubblica di tipo CWnd*.

In genere, si imposta questa variabile membro quando si esegue l'override di InitInstance. In un thread di lavoro il valore di questo membro dati viene ereditato dal thread padre.

CWinThread::OnIdle

Eseguire l'override di questa funzione membro per eseguire l'elaborazione inattiva.

virtual BOOL OnIdle(LONG lCount);

Parametri

lCount
Un contatore incrementato ogni volta OnIdle che viene chiamato quando la coda dei messaggi del thread è vuota. Questo conteggio viene reimpostato su 0 ogni volta che viene elaborato un nuovo messaggio. È possibile usare il lCount parametro per determinare il periodo di inattività del thread senza elaborare un messaggio.

Valore restituito

Diverso da zero per ricevere più tempo di elaborazione inattiva; 0 se non è necessario più tempo di elaborazione inattiva.

Osservazioni:

OnIdle viene chiamato nel ciclo di messaggi predefinito quando la coda dei messaggi del thread è vuota. Usare l'override per chiamare le attività del gestore inattivo in background.

OnIdle deve restituire 0 per indicare che non è necessario alcun tempo di elaborazione inattiva aggiuntivo. Il lCount parametro viene incrementato ogni volta OnIdle che viene chiamato quando la coda dei messaggi è vuota e viene reimpostata su 0 ogni volta che viene elaborato un nuovo messaggio. È possibile chiamare le diverse routine inattive in base a questo conteggio.

L'implementazione predefinita di questa funzione membro libera oggetti temporanei e librerie di collegamento dinamico inutilizzate dalla memoria.

Questa funzione membro viene usata solo nei thread dell'interfaccia utente.

Poiché l'applicazione non può elaborare i messaggi fino a OnIdle quando non viene restituito, non eseguire attività lunghe in questa funzione.

CWinThread::operator HANDLE

Recupera l'handle dell'oggetto CWinThread .

operator HANDLE() const;

Valore restituito

In caso di esito positivo, l'handle dell'oggetto thread; in caso contrario, NULL.

Osservazioni:

Usare l'handle per chiamare direttamente le API di Windows.

CWinThread::PostThreadMessage

Chiamato per pubblicare un messaggio definito dall'utente in un altro CWinThread oggetto .

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

Parametri

message
ID del messaggio definito dall'utente.

wParam
Primo parametro del messaggio.

lParam
Secondo parametro del messaggio.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0.

Osservazioni:

Il messaggio inviato viene mappato al gestore di messaggi appropriato dalla macro ON_THREAD_MESSAGEdella mappa messaggi .

CWinThread::PreTranslateMessage

Eseguire l'override di questa funzione per filtrare i messaggi della finestra prima che vengano inviati alle funzioni TranslateMessage di Windows e DispatchMessage.

virtual BOOL PreTranslateMessage(MSG* pMsg);

Parametri

pMsg
Punta a una MSG struttura contenente il messaggio da elaborare.

Valore restituito

Diverso da zero se il messaggio è stato elaborato completamente in PreTranslateMessage e non deve essere elaborato ulteriormente. Zero se il messaggio deve essere elaborato in modo normale.

Osservazioni:

Questa funzione membro viene usata solo nei thread dell'interfaccia utente.

CWinThread::ProcessMessageFilter

La funzione hook del framework chiama questa funzione membro per filtrare e rispondere a determinati messaggi di Windows.

virtual BOOL ProcessMessageFilter(
    int code,
    LPMSG lpMsg);

Parametri

code
Specifica un codice hook. Questa funzione membro usa il codice per determinare come elaborare lpMsg.

lpMsg
Puntatore a una struttura di Windows.MSG

Valore restituito

Diverso da zero se il messaggio viene elaborato; in caso contrario, 0.

Osservazioni:

Una funzione hook elabora gli eventi prima che vengano inviati all'elaborazione normale dei messaggi dell'applicazione.

Se si esegue l'override di questa funzionalità avanzata, assicurarsi di chiamare la versione della classe base per gestire l'elaborazione hook del framework.

CWinThread::ProcessWndProcException

Il framework chiama questa funzione membro ogni volta che il gestore non rileva un'eccezione generata in uno dei gestori di comandi o messaggi del thread.

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

Parametri

e
Punta a un'eccezione non gestita.

pMsg
Punta a una MSG struttura contenente informazioni sul messaggio di Windows che ha causato la generazione di un'eccezione da parte del framework.

Valore restituito

-1 se viene generata un'eccezione WM_CREATE ; in caso contrario, 0.

Osservazioni:

Non chiamare direttamente questa funzione membro.

L'implementazione predefinita di questa funzione membro gestisce solo le eccezioni generate dai messaggi seguenti:

Comando	Azione
WM_CREATE	Fallire.
WM_PAINT	Convalidare la finestra interessata, impedendo così la generazione di un altro WM_PAINT messaggio.

Eseguire l'override di questa funzione membro per fornire la gestione globale delle eccezioni. Chiamare la funzionalità di base solo se si desidera visualizzare il comportamento predefinito.

Questa funzione membro viene usata solo nei thread con un message pump.

CWinThread::PumpMessage

Contiene il ciclo di messaggi del thread.

virtual BOOL PumpMessage();

Osservazioni:

PumpMessage contiene il ciclo di messaggi del thread. PumpMessage viene chiamato da CWinThread per pompare i messaggi del thread. È possibile chiamare PumpMessage direttamente per forzare l'elaborazione dei messaggi oppure eseguire l'override PumpMessage per modificarne il comportamento predefinito.

È consigliabile chiamare PumpMessage direttamente ed eseguire l'override del comportamento predefinito solo per gli utenti avanzati.

CWinThread::ResumeThread

Chiamato per riprendere l'esecuzione di un thread sospeso dalla SuspendThread funzione membro o di un thread creato con il CREATE_SUSPENDED flag .

DWORD ResumeThread();

Valore restituito

Il conteggio delle sospensioni precedenti del thread se ha esito positivo; 0xFFFFFFFF altrimenti. Se il valore restituito è zero, il thread corrente non è stato sospeso. Se il valore restituito è uno, il thread è stato sospeso, ma ora viene riavviato. Qualsiasi valore restituito maggiore di uno indica che il thread rimane sospeso.

Osservazioni:

Il numero di sospensioni del thread corrente viene ridotto di uno. Se il conteggio delle sospensioni viene ridotto a zero, il thread riprende l'esecuzione; in caso contrario, il thread rimane sospeso.

CWinThread::Run

Fornisce un ciclo di messaggi predefinito per i thread dell'interfaccia utente.

virtual int Run();

Valore restituito

Valore int restituito dal thread. Questo valore può essere recuperato chiamando GetExitCodeThread.

Osservazioni:

Run acquisisce e invia messaggi di Windows fino a quando l'applicazione non riceve un WM_QUIT messaggio. Se la coda di messaggi del thread non contiene attualmente messaggi, Run chiama OnIdle per eseguire l'elaborazione inattiva. I messaggi in arrivo passano alla funzione membro per l'elaborazione PreTranslateMessage speciale e quindi alla funzione TranslateMessage Windows per la traduzione della tastiera standard. Infine, viene chiamata la DispatchMessage funzione Windows.

Run viene raramente sottoposto a override, ma è possibile eseguirne l'override per implementare un comportamento speciale.

Questa funzione membro viene usata solo nei thread dell'interfaccia utente.

CWinThread::SetThreadPriority

Questa funzione imposta il livello di priorità del thread corrente all'interno della relativa classe di priorità.

BOOL SetThreadPriority(int nPriority);

Parametri

nPriority
Specifica il nuovo livello di priorità del thread all'interno della relativa classe di priorità. Questo parametro deve essere uno dei valori seguenti, elencati dalla priorità più alta al più basso:

• THREAD_PRIORITY_TIME_CRITICAL

• THREAD_PRIORITY_HIGHEST

• THREAD_PRIORITY_ABOVE_NORMAL

• THREAD_PRIORITY_NORMAL

• THREAD_PRIORITY_BELOW_NORMAL

• THREAD_PRIORITY_LOWEST

• THREAD_PRIORITY_IDLE

Per altre informazioni su queste priorità, vedere SetThreadPriority in Windows SDK.

Valore restituito

Diverso da zero se la funzione ha avuto esito positivo; in caso contrario, 0.

Osservazioni:

Può essere chiamato solo dopo CreateThread che è stato restituito correttamente.

CWinThread::SuspendThread

Incrementa il conteggio delle sospensioni del thread corrente.

DWORD SuspendThread();

Valore restituito

Il conteggio delle sospensioni precedenti del thread se ha esito positivo; 0xFFFFFFFF altrimenti.

Osservazioni:

Se un thread ha un conteggio di sospensione superiore a zero, tale thread non viene eseguito. Il thread può essere ripreso chiamando la ResumeThread funzione membro.

Vedi anche

CCmdTarget Classe
Grafico della gerarchia
CWinApp Classe
CCmdTarget Classe