Classe CThreadPool

Essa classe fornece um pool de threads de trabalho que processam uma fila de itens de trabalho.

Sintaxe

template <class Worker, class ThreadTraits = DefaultThreadTraits>
class CThreadPool : public IThreadPoolConfig

Parâmetros

Trabalhador
A classe em conformidade com o arquétipo de trabalho que fornece o código usado para processar os itens de trabalho na fila no pool de threads.

ThreadTraits
A classe que fornece a função usada para criar os threads no pool.

Membros

Construtores públicos

Métodos públicos

Comentários

Os threads no pool são criados e destruídos quando o pool é inicializado, redimensionado ou encerrado. Uma instância da classe Trabalho será criada na pilha de cada thread de trabalho no pool. O tempo de vida de cada instância será o mesmo tempo de vida do thread.

Imediatamente após a criação de um thread, Worker::Initialize será chamado no objeto associado a esse thread. Imediatamente antes da destruição de um thread, Worker::Terminate será chamado. Ambos os métodos devem aceitar um argumento void*. O valor desse argumento é passado para o pool de threads por meio do parâmetro pvWorkerParam de CThreadPool::Initialize.

Quando houver itens de trabalho na fila e threads de trabalho disponíveis para trabalho, um thread de trabalho efetuará pull de um item da fila e chamará o método Execute do objeto Trabalho para esse thread. Em seguida, três itens serão passados para o método: o item da fila, o mesmo pvWorkerParam passado para Trabalho:: Initialize e Trabalho:: Terminate e um ponteiro para a estrutura OVERLAPPED usada para a fila da porta de conclusão de E/S.

A classe Trabalho declara o tipo dos itens que serão colocados na fila no pool de threads fornecendo um typedef, Trabalho:: RequestType. É necessário que esse tipo possa ser convertido para e de um ULONG_PTR.

Um exemplo de uma classe Trabalho é a classe CNonStatelessWorker.

Hierarquia de herança

IUnknown

IThreadPoolConfig

CThreadPool

Requisitos

Cabeçalho: atlutil.h

CThreadPool::AddRef

Implementação de IUnknown::AddRef.

ULONG STDMETHODCALLTYPE AddRef() throw();

Valor de retorno

Sempre retorna 1.

Comentários

Essa classe não implementa o controle de tempo de vida usando a contagem de referências.

CThreadPool::CThreadPool

O construtor para o pool de threads.

CThreadPool() throw();

Comentários

Inicializa o valor de tempo limite para ATLS_DEFAULT_THREADPOOLSHUTDOWNTIMEOUT. O tempo padrão é 36 segundos. Se necessário, você poderá definir seu próprio valor inteiro positivo para esse símbolo antes de incluir atlutil.h.

CThreadPool::~CThreadPool

O destruidor do pool de threads.

~CThreadPool() throw();

Comentários

Chamadas CThreadPool::Shutdown.

CThreadPool::GetNumThreads

Chame esse método para obter o número de threads no pool.

int GetNumThreads() throw();

Valor de retorno

Retorna o número de threads no pool.

CThreadPool::GetQueueHandle

Chame esse método para obter o identificador da porta de conclusão de E/S usada para colocar na fila os itens de trabalho.

HANDLE GetQueueHandle() throw();

Valor de retorno

Retornará o manipulador de fila ou NULL se o pool de threads não inicializar.

CThreadPool::GetSize

Chame esse método para obter o número de threads no pool.

HRESULT STDMETHODCALLTYPE GetSize(int* pnNumThreads) throw();

Parâmetros

pnNumThreads
[out] Endereço da variável que receberá o número de threads do pool, em caso de êxito.

Valor de retorno

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

CThreadPool::GetTimeout

Chame esse método para obter o tempo máximo em milissegundos que o pool de threads aguardará o desligamento de um thread.

HRESULT STDMETHODCALLTYPE GetTimeout(DWORD* pdwMaxWait) throw();

Parâmetros

pdwMaxWait
[out] Endereço da variável que receberá o tempo máximo em milissegundos que o pool de threads aguardará para que um thread seja desligado, em caso de êxito.

Valor de retorno

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

Comentários

Esse valor temporal será usado por CThreadPool::Shutdown se nenhum outro valor for fornecido a esse método.

CThreadPool::Initialize

Chame esse método para inicializar o pool de threads.

HRESULT Initialize(
    void* pvWorkerParam = NULL,
    int nNumThreads = 0,
    DWORD dwStackSize = 0,
    HANDLE hCompletion = INVALID_HANDLE_VALUE) throw();

Parâmetros

pvWorkerParam
O parâmetro de trabalho a ser passado para os métodos Initialize, Execute e Terminate.

nNumThreads
O número solicitado de threads no pool.

Se nNumThreads for negativo, o valor absoluto será multiplicado pelo número de processadores no computador para obter o número total de threads.

Se nNumThreads for zero, ATLS_DEFAULT_THREADSPERPROC será multiplicado pelo número de processadores no computador para obter o número total de threads. O padrão é 2 threads por processador. Se necessário, você poderá definir seu próprio valor inteiro positivo para esse símbolo antes de incluir atlutil.h.

dwStackSize
O tamanho da pilha para cada thread no pool.

hCompletion
O identificador de um objeto a ser associado à porta de conclusão.

Valor de retorno

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

CThreadPool::QueryInterface

Implementação de IUnknown::QueryInterface.

HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void** ppv) throw();

Comentários

Objetos dessa classe podem ser consultados com êxito para as interface IUnknown e IThreadPoolConfig.

CThreadPool::QueueRequest

Chame esse método para colocar na fila um item de trabalho que será manipulado por um thread no pool.

BOOL QueueRequest(Worker::RequestType request) throw();

Parâmetros

solicitação
A solicitação a ser colocada na fila.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Esse método adiciona um item de trabalho à fila. Os threads no pool retiram os itens da fila na ordem em que são recebidos.

CThreadPool::Release

Implementação de IUnknown::Release.

ULONG STDMETHODCALLTYPE Release() throw();

Valor de retorno

Sempre retorna 1.

Comentários

Essa classe não implementa o controle de tempo de vida usando a contagem de referências.

CThreadPool::SetSize

Chame esse método para definir o número de threads no pool.

HRESULT STDMETHODCALLTYPE SetSizeint nNumThreads) throw();

Parâmetros

nNumThreads
O número solicitado de threads no pool.

Se nNumThreads for negativo, o valor absoluto será multiplicado pelo número de processadores no computador para obter o número total de threads.

Se nNumThreads for zero, ATLS_DEFAULT_THREADSPERPROC será multiplicado pelo número de processadores no computador para obter o número total de threads. O padrão é 2 threads por processador. Se necessário, você poderá definir seu próprio valor inteiro positivo para esse símbolo antes de incluir atlutil.h.

Valor de retorno

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

Comentários

Se o número de threads especificado for menor do que o número de threads atualmente no pool, o objeto colocará na fila uma mensagem de desligamento para ser coletada por um thread em espera. Quando um thread em espera extrai a mensagem da fila, ele notifica o pool de threads e sai do procedimento de thread. Esse processo é repetido até que o número de threads no pool atinja o número especificado ou até que nenhum thread tenha saído dentro do período especificado por GetTimeout/ SetTimeout. Nessa situação, o método retornará um HRESULT correspondente a WAIT_TIMEOUT e a mensagem de desligamento pendente será cancelada.

CThreadPool::SetTimeout

Chame esse método para definir o tempo máximo em milissegundos que o pool de threads aguardará para que um thread seja desligado.

HRESULT STDMETHODCALLTYPE SetTimeout(DWORD dwMaxWait) throw();

Parâmetros

dwMaxWait
O tempo máximo solicitado em milissegundos que o pool de threads aguardará para que um thread seja desligado.

Valor de retorno

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

Comentários

O tempo limite é inicializado para ATLS_DEFAULT_THREADPOOLSHUTDOWNTIMEOUT. O tempo padrão é 36 segundos. Se necessário, você poderá definir seu próprio valor inteiro positivo para esse símbolo antes de incluir atlutil.h.

Observe que dwMaxWait é o tempo que o pool aguardará para que um único thread seja desligado. O tempo máximo que poderia ser necessário para remover vários threads do pool pode ser um pouco menor do que dwMaxWait multiplicado pelo número de threads.

CThreadPool::Shutdown

Chame esse método para desligar o pool de threads.

void Shutdown(DWORD dwMaxWait = 0) throw();

Parâmetros

dwMaxWait
O tempo máximo solicitado em milissegundos que o pool de threads aguardará para que um thread seja desligado. Se for 0, ou se nenhum valor for fornecido, esse método usará o tempo limite definido por CThreadPool::SetTimeout.

Comentários

Esse método envia uma solicitação de threads para todos os threads do pool. Se o tempo limite expirar, esse método chamará TerminateThread em threads não encerrados. Esse método é chamado automaticamente do destruidor da classe.

Confira também

Interface IThreadPoolConfig
DefaultThreadTraits
Classes