Classe CWorkerThread

  • Artigo

Essa classe cria um thread de trabalho ou usa um existente, aguarda um ou mais identificadores de objeto kernel e executa uma função de cliente especificada quando um dos identificadores é sinalizado.

Importante

Essa classe e os respectivos membros não podem ser usados em aplicativos executados no Windows Runtime.

Sintaxe

template <class ThreadTraits = DefaultThreadTraits>
class CWorkerThread

Parâmetros

ThreadTraits
A classe que fornece a função de criação de thread, como CRTThreadTraits ou Win32ThreadTraits.

Membros

Estruturas protegidas

Nome Descrição
WorkerClientEntry

Construtores públicos

Nome Descrição
CWorkerThread::CWorkerThread O construtor do thread de trabalho.
CWorkerThread::~CWorkerThread O destruidor do thread de trabalho.

Métodos públicos

Nome Descrição
CWorkerThread::AddHandle Chame esse método para adicionar o identificador de um objeto de espera à lista mantida pelo thread de trabalho.
CWorkerThread::AddTimer Chame esse método para adicionar o temporizador de um objeto de espera periódico à lista mantida pelo thread de trabalho.
CWorkerThread::GetThreadHandle Chame esse método para obter o identificador de thread do thread de trabalho.
CWorkerThread::GetThreadId Chame esse método para obter a ID de thread do thread de trabalho.
CWorkerThread::Initialize Chame esse método para inicializar o thread de trabalho.
CWorkerThread::RemoveHandle Chame esse método para remover um identificador da lista de objetos de espera.
CWorkerThread::Shutdown Chame esse método para desligar o thread de trabalho.

Comentários

Para usar CWorkerThread

  1. Crie uma instância dessa classe.

  2. Chame CWorkerThread::Initialize.

  3. Chame CWorkerThread::AddHandle com o identificador de um objeto kernel e um ponteiro para uma implementação de IWorkerThreadClient.

    - ou -

    Chame CWorkerThread::AddTimer com um ponteiro para uma implementação de IWorkerThreadClient.

  4. Implemente IWorkerThreadClient::Execute para executar alguma ação quando o identificador ou temporizador for sinalizado.

  5. Para remover um objeto da lista de objetos de espera, chame CWorkerThread::RemoveHandle.

  6. Para encerrar o thread, chame CWorkerThread::Shutdown.

Requisitos

Cabeçalho: atlutil.h

CWorkerThread::AddHandle

Chame esse método para adicionar o identificador de um objeto de espera à lista mantida pelo thread de trabalho.

HRESULT AddHandle(
    HANDLE hObject,
    IWorkerThreadClient* pClient,
    DWORD_PTR dwParam) throw();

Parâmetros

hObject
O identificador para um objeto de espera.

pClient
O ponteiro para a interface IWorkerThreadClient no objeto a ser chamado quando o identificador é sinalizado.

dwParam
O parâmetro a ser passado para IWorkerThreadClient::Execute quando o identificador é sinalizado.

Valor de Devolução

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

IWorkerThreadClient::Execute será chamado por meio de pClient quando o identificador, hObject, for sinalizado.

CWorkerThread::AddTimer

Chame esse método para adicionar o temporizador de um objeto de espera periódico à lista mantida pelo thread de trabalho.

HRESULT AddTimer(
    DWORD dwInterval,
    IWorkerThreadClient* pClient,
    DWORD_PTR dwParam,
    HANDLE* phTimer) throw();

Parâmetros

dwInterval
Especifica o período do temporizador em milissegundos.

pClient
O ponteiro para a interface IWorkerThreadClient no objeto a ser chamado quando o identificador é sinalizado.

dwParam
O parâmetro a ser passado para IWorkerThreadClient::Execute quando o identificador é sinalizado.

phTimer
[out] Endereço da variável HANDLE que, com êxito, recebe o identificador para o temporizador recém-criado.

Valor de Devolução

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

IWorkerThreadClient::Execute será chamado por meio de pClient quando o temporizador for sinalizado.

Passe o identificador de temporizador do phTimer para CWorkerThread::RemoveHandle para fechar o temporizador.

CWorkerThread::CWorkerThread

O construtor .

CWorkerThread() throw();

CWorkerThread::~CWorkerThread

O destruidor.

~CWorkerThread() throw();

Comentários

Chame CWorkerThread::Shutdown.

CWorkerThread::GetThreadHandle

Chame esse método para obter o identificador de thread do thread de trabalho.

HANDLE GetThreadHandle() throw();

Valor de Devolução

Retornará o identificador de thread ou NULL se o thread de trabalho não tiver sido inicializado.

CWorkerThread::GetThreadId

Chame esse método para obter a ID de thread do thread de trabalho.

DWORD GetThreadId() throw();

Valor de Devolução

Retornará a ID de thread ou NULL se o thread de trabalho não tiver sido inicializado.

CWorkerThread::Initialize

Chame esse método para inicializar o thread de trabalho.

HRESULT Initialize() throw();

HRESULT Initialize(CWorkerThread<ThreadTraits>* pThread) throw();

Parâmetros

pThread
Um thread de trabalho existente.

Valor de Devolução

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Esse método deve ser chamado para inicializar o objeto após a criação ou após uma chamada para CWorkerThread::Shutdown.

Para que dois ou mais objetos CWorkerThread usem o mesmo thread de trabalho, inicialize um deles sem passar argumentos e passe um ponteiro para esse objeto para os métodos Initialize de outros. Os objetos inicializados usando o ponteiro devem ser desligados antes do objeto usado para inicializá-los.

Confira CWorkerThread::Shutdown para obter informações sobre como o comportamento desse método muda quando inicializado usando um ponteiro para um objeto existente.

CWorkerThread::RemoveHandle

Chame esse método para remover um identificador da lista de objetos de espera.

HRESULT RemoveHandle(HANDLE hObject) throw();

Parâmetros

hObject
O identificador a ser removido.

Valor de Devolução

Retornará S_OK se houver êxito ou um erro HRESULT, em caso de falha.

Comentários

Quando o identificador for removido, IWorkerThreadClient::CloseHandle será chamado no objeto associado que foi passado para AddHandle. Se essa chamada falhar, CWorkerThread chamará a função CloseHandle do Windows no identificador.

CWorkerThread::Shutdown

Chame esse método para desligar o thread de trabalho.

HRESULT Shutdown(DWORD dwWait = ATL_WORKER_THREAD_WAIT) throw();

Parâmetros

dwWait
O tempo em milissegundos para aguardar o desligamento do thread de trabalho. ATL_WORKER_THREAD_WAIT é padronizado para 10 segundos. Se necessário, você pode definir seu próprio valor para esse símbolo antes de incluir atlutil.h.

Valor de Devolução

Retorna S_OK em caso de êxito, ou um erro HRESULT em caso de falha, como se o valor do tempo limite, dwWait, tivesse sido excedido.

Comentários

Para reutilizar o objeto, chame CWorkerThread::Initialize depois de chamar esse método.

Observe que chamar Shutdown em um objeto inicializado com um ponteiro para outro objeto CWorkerThread não tem efeito e sempre retorna S_OK.

Confira também

DefaultThreadTraits
Classes
Multithreading: criando threads de trabalho
Interface IWorkerThreadClient