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 que segue o arquétipo worker fornece o código usado para processar os itens de trabalho enfileirados 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

Observações

Os threads no pool são criados e destruídos quando o pool é inicializado, redimensionado ou desligado. Uma instância de Class Worker será criada na pilha de cada thread worker do pool. Cada instância viverá durante toda a vida útil do fio.

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 fio, será chamado Worker::Terminate Ambos os métodos devem aceitar um void* argumento. O valor deste argumento é passado para o pool de threads através do parâmetro pvWorkerParam do CThreadPool::Initialize.

Quando há itens de trabalho na fila e threads worker disponíveis para trabalho, um worker thread puxa um item da fila e chama o Execute método do objeto Worker para esse thread. Três itens são então passados para o método: o item da fila, o mesmo pvWorkerParam passado para Worker:: Initialize e Worker:: Terminate, e um ponteiro para a estrutura OVERLAPPED usada para a fila da porta de conclusão de IO.

A classe Worker declara o tipo dos itens que serão enfileirados no pool de threads fornecendo um typedef, Worker:: RequestType. Este tipo deve ser capaz de ser lançado para e de um ULONG_PTR.

Um exemplo de classe Worker é CNonStatelessWorker Class.

Hierarquia de herança

IUnknown

IThreadPoolConfig

CThreadPool

Requerimentos

Cabeçalho: atlutil.h

CThreadPool::AddRef

Implementação de IUnknown::AddRef.

ULONG STDMETHODCALLTYPE AddRef() throw();

Valor de retorno

Devolve sempre 1.

Observações

Esta classe não implementa controlo de tempo de vida usando contagem de referências.

CThreadPool::CThreadPool

O construtor para o pool de threads.

CThreadPool() throw();

Observações

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

CThreadPool::~CThreadPool

O destruidor para o pool de fios.

~CThreadPool() throw();

Observações

Chama CThreadPool::Encerramento.

CThreadPool::GetNumThreads

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

int GetNumThreads() throw();

Valor de retorno

Devolve o número de threads no pool.

CThreadPool::GetQueueHandle

Chame este método para obter o handle da porta de completação de IO usada para colocar os itens de trabalho em fila.

HANDLE GetQueueHandle() throw();

Valor de retorno

Devolve o handle da fila ou NULL se o pool de threads não tiver sido inicializado.

CThreadPool::GetSize

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

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

Parâmetros

pnNumThreads
[fora] Endereço da variável que, em caso de sucesso, recebe o número de threads no pool.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

CThreadPool::GetTimeout

Chame este método para obter o tempo máximo em milissegundos em que o pool de threads espera que um thread desligue.

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

Parâmetros

pdwMaxWait
[fora] Endereço da variável que, em caso de sucesso, recebe o tempo máximo em milissegundos em que o pool de threads espera que um thread seja desligado.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Este valor de timeout é usado pelo CThreadPool::Shutdown se não for fornecido outro valor a esse método.

CThreadPool::Inicializar

Chame este 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 worker a ser passado para os métodos do Initializeobjeto worker thread , Execute, Terminate e dos métodos.

nNumThreads
O número pedido de tópicos no pool.

Se o nNumThreads for negativo, o seu valor absoluto será multiplicado pelo número de processadores na máquina para obter o número total de threads.

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

dwStackSize
O tamanho da pilha para cada thread do pool.

hConclusão
O handle de um objeto a associar à porta de completão.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

CThreadPool::QueryInterface

Implementação de IUnknown::QueryInterface.

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

Observações

Os objetos desta classe podem ser consultados com sucesso para as IUnknown interfaces e IThreadPoolConfig .

CThreadPool::FileRequest

Chame este método para enfileirar um item de trabalho a ser tratado por um thread no pool.

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

Parâmetros

pedido
O pedido para estar em fila.

Valor de retorno

Retorna VERDADEIRO em caso de sucesso, FALSO em caso de falha.

Observações

Este método adiciona um item de trabalho à fila. Os threads do pool selecionam os itens da fila pela ordem em que são recebidos.

CThreadPool::Lançamento

Implementação de IUnknown::Release.

ULONG STDMETHODCALLTYPE Release() throw();

Valor de retorno

Devolve sempre 1.

Observações

Esta classe não implementa controlo de tempo de vida usando contagem de referências.

CThreadPool::SetSize

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

HRESULT STDMETHODCALLTYPE SetSize(int nNumThreads) throw();

Parâmetros

nNumThreads
O número pedido de tópicos no pool.

Se o nNumThreads for negativo, o seu valor absoluto será multiplicado pelo número de processadores na máquina para obter o número total de threads.

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

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

Se o número de threads especificados for inferior ao número de threads atualmente no pool, o objeto coloca uma mensagem de encerramento na fila para ser captada por um thread em espera. Quando um thread em espera retira a mensagem da fila, notifica o pool de threads e sai do procedimento do thread. Este processo repete-se até que o número de threads no pool atinja o número especificado ou até que nenhuma thread tenha saído dentro do período especificado pelo GetTimeout/ SetTimeout. Nesta situação, o método devolverá um HRESULT correspondente a WAIT_TIMEOUT e a mensagem de encerramento pendente será cancelada.

CThreadPool::SetTimeout

Chame este método para definir o tempo máximo em milissegundos em que o pool de threads espera que um thread desligue.

HRESULT STDMETHODCALLTYPE SetTimeout(DWORD dwMaxWait) throw();

Parâmetros

dwMaxWait
O tempo máximo solicitado em milissegundos em que o pool de threads espera que um thread desligue.

Valor de retorno

Devolve S_OK em caso de sucesso, ou um erro HRESULT em caso de falha.

Observações

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

Note que dwMaxWait é o momento em que o pool espera que um único thread desligue. O tempo máximo que poderia ser necessário para remover múltiplos threads do pool poderia ser ligeiramente inferior ao dwMaxWait multiplicado pelo número de threads.

CThreadPool::Encerramento

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

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

Parâmetros

dwMaxWait
O tempo máximo solicitado em milissegundos em que o pool de threads espera que um thread desligue. Se 0 ou nenhum valor for fornecido, este método usará o timeout definido por CThreadPool::SetTimeout.

Observações

Este método envia um pedido de desligamento para todos os tópicos do pool. Se o timeout expirar, este método chamará o TerminateThread em qualquer thread que não tenha saído. Este método é chamado automaticamente do destruidor da classe.

Consulte também

IThreadPoolConfig Interface
DefaultThreadTraits
Classes