Classe CWinThread

Representa um thread de execução dentro de um aplicativo.

Sintaxe

class CWinThread : public CCmdTarget

Membros

Construtores públicos

Nome	Descrição
CWinThread::CWinThread	Constrói um objeto CWinThread.

Métodos públicos

Nome	Descrição
CWinThread::CreateThread	Inicia a execução de um objeto CWinThread.
CWinThread::ExitInstance	Substitua para limpar quando o thread for encerrado.
CWinThread::GetMainWnd	Recupera um ponteiro para a janela principal do thread.
CWinThread::GetThreadPriority	Obtém a prioridade do thread atual.
CWinThread::InitInstance	Substitua para executar a inicialização da instância de thread.
CWinThread::IsIdleMessage	Verifica se há mensagens especiais.
CWinThread::OnIdle	Substitua para executar o processamento de tempo ocioso específico do thread.
CWinThread::PostThreadMessage	Posta uma mensagem em outro objeto CWinThread.
CWinThread::PreTranslateMessage	Filtra as mensagens antes de serem enviadas para as funções do Windows TranslateMessage e DispatchMessage.
CWinThread::ProcessMessageFilter	Intercepta determinadas mensagens antes de chegarem ao aplicativo.
CWinThread::ProcessWndProcException	Intercepta todas as exceções sem tratamento geradas pelos manipuladores de comando e mensagem do thread.
CWinThread::PumpMessage	Contém o loop de mensagem do thread.
CWinThread::ResumeThread	Diminui a contagem de suspensão de um thread.
CWinThread::Run	Função de controle para threads com uma bomba de mensagem. Substituição para personalizar o loop de mensagem padrão.
CWinThread::SetThreadPriority	Define a prioridade do thread atual.
CWinThread::SuspendThread	Incrementa a contagem de suspensão de um thread.

Operadores públicos

Nome	Descrição
CWinThread::operator HANDLE	Recupera o identificador do objeto CWinThread.

Membros de Dados Públicos

Nome	Descrição
CWinThread::m_bAutoDelete	Especifica se o objeto deve ser destruído no encerramento do thread.
CWinThread::m_hThread	Identificador para o thread atual.
CWinThread::m_nThreadID	ID do thread atual.
CWinThread::m_pActiveWnd	Ponteiro para a janela principal do aplicativo de contêiner quando um servidor OLE está ativo no local.
CWinThread::m_pMainWnd	Mantém um ponteiro para a janela principal do aplicativo.

Comentários

O thread principal da execução geralmente é fornecido por um objeto derivado de CWinApp; CWinApp é derivado de CWinThread. Objetos CWinThread adicionais permitem vários threads em um determinado aplicativo.

Há dois tipos gerais de threads a que CWinThread dá suporte: threads de trabalho e threads de interface do usuário. Os threads de trabalho não têm nenhuma bomba de mensagem: por exemplo, um thread que executa cálculos em segundo plano em um aplicativo de planilha. Os threads de interface do usuário têm uma bomba de mensagem e mensagens de processo recebidas do sistema. CWinApp e classes derivadas dele são exemplos de threads de interface do usuário. Outros threads de interface do usuário também podem ser derivados diretamente de CWinThread.

Objetos de classe CWinThread normalmente existem durante a duração do thread. Se você quiser modificar esse comportamento, defina m_bAutoDelete como FALSE.

A classe CWinThread é necessária para tornar seu código e MFC totalmente thread-safe. Os dados locais de thread usados pela estrutura para manter informações específicas do thread são gerenciados por objetos CWinThread. Devido a essa dependência de CWinThread para lidar com os dados locais de thread, qualquer thread que usa MFC deve ser criado pelo MFC. Por exemplo, um thread criado pela função de tempo de execução _beginthread, _beginthreadex não pode usar nenhuma API MFC.

Para criar um thread, chame AfxBeginThread. Há duas formas, dependendo se você deseja um thread de trabalho ou interface do usuário. Se você quiser um thread de interface do usuário, passe para AfxBeginThread um ponteiro para a classe CRuntimeClass derivada de CWinThread. Se você quiser criar um thread de trabalho, passe para AfxBeginThread um ponteiro para a função de controle e o parâmetro para a função de controle. Para threads de trabalho e threads de interface do usuário, você pode especificar parâmetros opcionais que modificam prioridade, tamanho da pilha, sinalizadores de criação e atributos de segurança. AfxBeginThread retornará um ponteiro para o novo objeto CWinThread.

Em vez de chamar AfxBeginThread, você pode construir um objeto derivado de CWinThreade, em seguida, chamar CreateThread. Esse método de construção em duas fases será útil se você quiser reutilizar o objeto CWinThread entre a criação sucessiva e terminações de execuções de thread.

Para mais informações sobre CWinThread, confira os artigos Multithreading com C++ e MFC, Multithreading: como criar threads de interface do usuário, Multithreading: como criar threads de trabalho e Multithreading: como usar as classes de sincronização.

Hierarquia de herança

CObject

CCmdTarget

CWinThread

Requisitos

Cabeçalho: afxwin.h

CWinThread::CreateThread

Cria um thread para ser executado no espaço de endereço do processo de chamada.

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

Parâmetros

dwCreateFlags
Especifica um sinalizador adicional que controla a criação do thread. Esse sinalizador pode conter um de dois valores:

• CREATE_SUSPENDED Iniciar o thread com um suspender contagem de um. Use CREATE_SUSPENDED se quiser inicializar os dados de membro do objeto CWinThread, como m_bAutoDelete ou qualquer membro da classe derivada, antes que o thread comece a ser executado. Depois que a inicialização for concluída, use o CWinThread::ResumeThread para iniciar a execução do thread. O thread não será executado até que CWinThread::ResumeThread seja chamado.

• 0 Inicie o thread imediatamente após a criação.

nStackSize
Especifica o tamanho em bytes da pilha para o novo thread. Se 0, o tamanho da pilha será padrão para o mesmo tamanho do thread primário do processo.

lpSecurityAttrs
Aponta para uma estrutura SECURITY_ATTRIBUTES que especifica os atributos de segurança do thread.

Valor de retorno

Não zero se o thread tiver sido criado com êxito; caso contrário, 0.

Comentários

Use AfxBeginThread para criar um objeto thread e executá-lo em uma etapa. Use CreateThread se quiser reutilizar o objeto thread entre a criação sucessiva e o encerramento de execuções de thread.

CWinThread::CWinThread

Constrói um objeto CWinThread.

CWinThread();

Comentários

Para iniciar a execução do thread, chame a função de membro CreateThread. Você geralmente criará threads chamando AfxBeginThread, o que chamará esse construtor e CreateThread.

CWinThread::ExitInstance

Chamado pela estrutura de dentro de uma função de membro Run raramente substituída para sair dessa instância do thread ou se uma chamada a InitInstance falhar.

virtual int ExitInstance();

Valor de retorno

O código de saída do thread; 0 não indica erros e valores maiores que 0 indicam um erro. Esse valor pode ser recuperado chamando GetExitCodeThread.

Comentários

Não chame essa função de membro de qualquer lugar, mas dentro da função de membro Run. Essa função de membro é usada somente em threads de interface do usuário.

A implementação padrão dessa função exclui o objeto CWinThread se m_bAutoDelete é TRUE. Substitua essa função se você quiser executar uma limpeza adicional quando o thread for encerrado. Sua implementação de ExitInstance deve chamar a versão da classe base depois que o código for executado.

CWinThread::GetMainWnd

Se o aplicativo for um servidor OLE, chame essa função para recuperar um ponteiro para a janela principal ativa do aplicativo em vez de fazer referência direta ao membro m_pMainWnd do objeto do aplicativo.

virtual CWnd* GetMainWnd();

Valor de retorno

Essa função retorna um ponteiro para um dos dois tipos de janelas. Se o thread fizer parte de um servidor OLE e tiver um objeto ativo no local dentro de um contêiner ativo, essa função retornará o membro de dados CWinApp::m_pActiveWnd do objeto CWinThread.

Se não houver nenhum objeto ativo no local dentro de um contêiner ou seu aplicativo não for um servidor OLE, essa função retornará o membro de dados m_pMainWnd do objeto de thread.

Comentários

Para threads de interface do usuário, isso equivale a se referir diretamente ao membro m_pActiveWnd do objeto do aplicativo.

Se o aplicativo não for um servidor OLE, chamar essa função será equivalente a fazer referência direta ao membro m_pMainWnd do objeto do aplicativo.

Substitua essa função para modificar o comportamento padrão.

CWinThread::GetThreadPriority

Obtém o nível de prioridade de thread atual desse thread.

int GetThreadPriority();

Valor de retorno

O nível de prioridade atual do thread dentro de sua classe de prioridade. O valor retornado será um dos seguintes, listados da prioridade mais alta para a mais baixa:

• THREAD_PRIORITY_TIME_CRITICAL

• THREAD_PRIORITY_HIGHEST

• THREAD_PRIORITY_ABOVE_NORMAL

• THREAD_PRIORITY_NORMAL

• THREAD_PRIORITY_BELOW_NORMAL

• THREAD_PRIORITY_LOWEST

• THREAD_PRIORITY_IDLE

Para mais informações sobre essas prioridades, confira SetThreadPriority o SDK do Windows.

CWinThread::InitInstance

InitInstance deve ser substituído para inicializar cada nova instância de um thread de interface do usuário.

virtual BOOL InitInstance();

Valor de retorno

Não zero se a inicialização for bem-sucedida; caso contrário, 0.

Comentários

Normalmente, você substitui InitInstance para executar tarefas que devem ser concluídas quando um thread é criado pela primeira vez.

Essa função de membro é usada somente em threads de interface do usuário. Execute a inicialização de threads de trabalho na função de controle passada para AfxBeginThread.

CWinThread::IsIdleMessage

Substitua essa função para impedir que OnIdle seja chamado depois que mensagens específicas forem geradas.

virtual BOOL IsIdleMessage(MSG* pMsg);

Parâmetros

pMsg
Aponta para a mensagem atual que está sendo processada.

Valor de retorno

Não zero se OnIdle precisar ser chamado após o processamento da mensagem; caso contrário, 0.

Comentários

A implementação padrão não chama OnIdle após mensagens de mouse redundantes e mensagens geradas por sinais de interpolação piscando.

Se um aplicativo tiver criado um temporizador curto, OnIdle será chamado com frequência, causando problemas de desempenho. Para melhorar o desempenho desse aplicativo, substitua IsIdleMessage na classe derivada de CWinApp do aplicativo para verificar se há mensagens WM_TIMER da seguinte maneira:

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

Tratar WM_TIMER dessa forma melhorará o desempenho de aplicativos que usam temporizadores curtos.

CWinThread::m_bAutoDelete

Especifica se o objeto CWinThread deve ser excluído automaticamente no encerramento do thread.

BOOL m_bAutoDelete;

Comentários

O membro de dados m_bAutoDelete é uma variável pública do tipo BOOL.

O valor de m_bAutoDelete não afeta como o identificador de thread subjacente é fechado, mas afeta o tempo de fechamento do identificador. O identificador de thread sempre é fechado quando o objeto CWinThread é destruído.

CWinThread::m_hThread

Identificador para o thread anexado a este CWinThread.

HANDLE m_hThread;

Comentários

Esse membro de dados m_hThread é uma variável pública do tipo HANDLE. Ele só será válido se o objeto de thread de kernel subjacente existir no momento e o identificador ainda não tiver sido fechado.

O destruidor CWinThread chama CloseHandle em m_hThread. Se m_bAutoDelete for TRUE quando o thread for encerrado, o objeto CWinThread será destruído, o que invalida todos os ponteiros para o objeto CWinThread e suas variáveis de membro. Talvez seja necessário que o membro m_hThread verifique o valor de saída do thread ou aguarde um sinal. Para manter o objeto CWinThread e seu membro m_hThread durante a execução do thread e depois que ele for encerrado, defina m_bAutoDelete como FALSE antes de permitir que a execução do thread continue. Caso contrário, o thread poderá terminar, destruir o objeto CWinThread e fechar o identificador antes de você tentar usá-lo. Se você usar essa técnica, será responsável pela exclusão do objeto CWinThread.

CWinThread::m_nThreadID

ID do thread anexado a este CWinThread.

DWORD m_nThreadID;

Comentários

Esse membro de dados m_nThreadID é uma variável pública do tipo DWORD. Ele só será válido se o objeto de thread de kernel subjacente existir no momento. Veja também comentários sobre o tempo de vida de m_hThread.

Exemplo

Confira o exemplo de AfxGetThread.

CWinThread::m_pActiveWnd

Use esse membro de dados para armazenar um ponteiro para o objeto de janela ativa do thread.

CWnd* m_pActiveWnd;

Comentários

A biblioteca Microsoft Foundation Class encerrará automaticamente o thread quando a janela referenciada por m_pActiveWnd for fechada. Se esse thread for o thread principal de um aplicativo, o aplicativo também será encerrado. Se esse membro de dados for NULL, a janela ativa do objeto CWinApp do aplicativo será herdada. m_pActiveWnd é uma variável pública do tipo CWnd*.

Normalmente, você define essa variável de membro ao substituir InitInstance. Em um thread de trabalho, o valor desse membro de dados é herdado de seu thread pai.

CWinThread::m_pMainWnd

Use esse membro de dados para armazenar um ponteiro para o objeto de janela principal do thread.

CWnd* m_pMainWnd;

Comentários

A biblioteca Microsoft Foundation Class encerrará automaticamente o thread quando a janela referenciada por m_pMainWnd for fechada. Se esse thread for o thread principal de um aplicativo, o aplicativo também será encerrado. Se esse membro de dados for NULL, a janela principal do objeto do aplicativo CWinApp será usada para determinar quando terminar o thread. m_pMainWnd é uma variável pública do tipo CWnd*.

Normalmente, você define essa variável de membro ao substituir InitInstance. Em um thread de trabalho, o valor desse membro de dados é herdado de seu thread pai.

CWinThread::OnIdle

Substitua essa função de membro para executar o processamento de tempo ocioso.

virtual BOOL OnIdle(LONG lCount);

Parâmetros

lCount
Um contador incrementado cada vez que OnIdle é chamado quando a fila de mensagens do thread está vazia. Essa contagem é redefinida para 0 sempre que uma nova mensagem é processada. Você pode usar o parâmetro lCount para determinar o período relativo de tempo que o thread ficou ocioso sem processar uma mensagem.

Valor de retorno

Não zero para receber mais tempo de processamento ocioso; 0 se não for necessário mais tempo de processamento ocioso.

Comentários

OnIdle é chamado no loop de mensagem padrão quando a fila de mensagens do thread está vazia. Use sua substituição para chamar tarefas próprias de manipulador ocioso em segundo plano.

OnIdle deve retornar 0 para indicar que nenhum tempo adicional de processamento ocioso é necessário. O parâmetro lCount é incrementado cada vez que OnIdle é chamado quando a fila de mensagens está vazia e é redefinido para 0 sempre que uma nova mensagem é processada. Você pode chamar suas diferentes rotinas ociosas com base nessa contagem.

A implementação padrão dessa função de membro libera objetos temporários e bibliotecas de link dinâmico não utilizados da memória.

Essa função de membro é usada somente em threads de interface do usuário.

Como o aplicativo não pode processar mensagens até que OnIdle retorne, não execute tarefas longas nessa função.

CWinThread::operator HANDLE

Recupera o identificador do objeto CWinThread.

operator HANDLE() const;

Valor de retorno

Se tiver êxito, o identificador do objeto thread; caso contrário, NULL.

Comentários

Use o identificador para chamar diretamente as APIs do Windows.

CWinThread::PostThreadMessage

Chamado para postar uma mensagem definida pelo usuário em outro objeto CWinThread.

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

Parâmetros

message
ID da mensagem definida pelo usuário.

wParam
Primeiro parâmetro de mensagem.

lParam
Segundo parâmetro de mensagem.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

A mensagem postada é mapeada para o manipulador de mensagens apropriado pela macro do mapa de mensagens ON_THREAD_MESSAGE.

Observação

Quando você chama PostThreadMessage, a mensagem é colocada na fila de mensagens do thread. No entanto, como as mensagens postadas dessa forma não estão associadas a uma janela, o MFC não as enviará para manipuladores de mensagens ou comandos. Para lidar com essas mensagens, substitua a função PreTranslateMessage() da classe derivada de CWinAppe manipule as mensagens manualmente.

CWinThread::PreTranslateMessage

Substitua essa função para filtrar mensagens de janela antes de serem enviadas para as funções do Windows TranslateMessage e DispatchMessage.

virtual BOOL PreTranslateMessage(MSG* pMsg);

Parâmetros

pMsg
Aponta para uma estrutura MSG que contém a mensagem a ser processada.

Valor de retorno

Não zero se a mensagem foi totalmente processada em PreTranslateMessage e não deve ser processada mais adiante. Zero se a mensagem deve ser processada da maneira normal.

Comentários

Essa função de membro é usada somente em threads de interface do usuário.

CWinThread::ProcessMessageFilter

A função de gancho da estrutura chama essa função de membro para filtrar e responder a determinadas mensagens do Windows.

virtual BOOL ProcessMessageFilter(
    int code,
    LPMSG lpMsg);

Parâmetros

code
Especifica um código de gancho. Essa função de membro usa o código para determinar como processar lpMsg.

lpMsg
Um ponteiro para uma estrutura MSG do Windows.

Valor de retorno

Diferente de zero se a mensagem for processada; caso contrário, 0.

Comentários

Uma função de gancho processa eventos antes de serem enviados para o processamento de mensagem normal do aplicativo.

Se você substituir esse recurso avançado, chame a versão de classe base para manter o processamento de gancho da estrutura.

CWinThread::ProcessWndProcException

A estrutura chama essa função de membro sempre que o manipulador não captura uma exceção gerada em um dos manipuladores de comando ou mensagem do thread.

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

Parâmetros

e
Aponta para uma exceção sem tratamento.

pMsg
Aponta para uma estrutura MSG que contém informações sobre a mensagem do Windows que fez com que a estrutura gerasse uma exceção.

Valor de retorno

-1 se uma exceção WM_CREATE for gerada; caso contrário, 0.

Comentários

Não chame essa função de membro diretamente.

A implementação padrão dessa função de membro trata apenas das exceções geradas com base nas seguintes mensagens:

Comando	Ação
WM_CREATE	Falhar.
WM_PAINT	Valide a janela afetada, impedindo que outra mensagem WM_PAINT seja gerada.

Substitua essa função de membro para fornecer tratamento global de suas exceções. Chame a funcionalidade base somente se você quiser exibir o comportamento padrão.

Essa função de membro é usada apenas em threads que têm uma bomba de mensagem.

CWinThread::PumpMessage

Contém o loop de mensagem do thread.

virtual BOOL PumpMessage();

Comentários

PumpMessage contém o loop de mensagem do thread. PumpMessage é chamado por CWinThread para bombear as mensagens do thread. Você pode chamar PumpMessage diretamente para forçar o processamento de mensagens ou substituir PumpMessage para alterar seu comportamento padrão.

Chamar PumpMessage diretamente e substituir seu comportamento padrão é recomendado apenas para usuários avançados.

CWinThread::ResumeThread

Chamado para retomar a execução de um thread que foi suspenso pela função de membro SuspendThread ou um thread criado com o sinalizador CREATE_SUSPENDED.

DWORD ResumeThread();

Valor de retorno

A contagem de suspensão anterior do thread, se bem-sucedida; caso contrário, 0xFFFFFFFF. Se o valor retornado for zero, o thread atual não será suspenso. Se o valor retornado for um, o thread foi suspenso, mas agora será reiniciado. Qualquer valor retornado maior que um significa que o thread permanece suspenso.

Comentários

A contagem de suspensão do thread atual é reduzida em um. Se a contagem de suspensão for reduzida a zero, o thread retomará a execução; caso contrário, o thread permanecerá suspenso.

CWinThread::Run

Fornece um loop de mensagem padrão para threads de interface do usuário.

virtual int Run();

Valor de retorno

Um valor int retornado pelo thread. Esse valor pode ser recuperado chamando GetExitCodeThread.

Comentários

Run adquire e despacha mensagens do Windows até que o aplicativo receba uma mensagem WM_QUIT. Se a fila de mensagens do thread não contiver mensagens no momento, Run chamará OnIdle para executar o processamento de tempo ocioso. As mensagens de entrada vão para a função de membro PreTranslateMessage para processamento especial e então para a função do Windows TranslateMessage para tradução de teclado padrão. Por fim, a função do Windows DispatchMessage é chamada.

Run raramente é substituído, mas você pode substituí-lo para implementar um comportamento especial.

Essa função de membro é usada somente em threads de interface do usuário.

CWinThread::SetThreadPriority

Essa função define o nível de prioridade do thread atual dentro de sua classe de prioridade.

BOOL SetThreadPriority(int nPriority);

Parâmetros

nPriority
Especifica o novo nível de prioridade de thread dentro de sua classe de prioridade. Esse parâmetro deve ser um dos seguintes valores, listados da prioridade mais alta para a mais baixa:

• THREAD_PRIORITY_TIME_CRITICAL

• THREAD_PRIORITY_HIGHEST

• THREAD_PRIORITY_ABOVE_NORMAL

• THREAD_PRIORITY_NORMAL

• THREAD_PRIORITY_BELOW_NORMAL

• THREAD_PRIORITY_LOWEST

• THREAD_PRIORITY_IDLE

Para mais informações sobre essas prioridades, confira SetThreadPriority o SDK do Windows.

Valor de retorno

Não zero se a função for bem-sucedida; caso contrário, 0.

Comentários

Ele só pode ser chamado após CreateThread ser retornado com êxito.

CWinThread::SuspendThread

Incrementa a contagem de suspensão do thread atual.

DWORD SuspendThread();

Valor de retorno

A contagem de suspensão anterior do thread, se bem-sucedida; caso contrário, 0xFFFFFFFF.

Comentários

Se qualquer thread tiver uma contagem de suspensão acima de zero, esse thread não será executado. O thread pode ser retomado chamando a função de membro ResumeThread.

Confira também

Classe CCmdTarget
Gráfico da hierarquia
Classe CWinApp
Classe CCmdTarget