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
| Nome | Descrição |
|---|---|
| CThreadPool::CThreadPool | O construtor para o pool de threads. |
| CThreadPool::~CThreadPool | O destruidor do pool de threads. |
Métodos públicos
| Nome | Descrição |
|---|---|
| CThreadPool::AddRef | Implementação de IUnknown::AddRef. |
| CThreadPool::GetNumThreads | Chame esse método para obter 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. |
| CThreadPool::GetSize | Chame esse método para obter o número de threads no pool. |
| 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. |
| CThreadPool::Initialize | Chame esse método para inicializar o pool de threads. |
| CThreadPool::QueryInterface | Implementação de IUnknown::QueryInterface. |
| CThreadPool::QueueRequest | Chame esse método para colocar na fila um item de trabalho que será manipulado por um thread no pool. |
| CThreadPool::Release | Implementação de IUnknown::Release. |
| CThreadPool::SetSize | Chame esse método para definir o número de threads no pool. |
| 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. |
| CThreadPool::Shutdown | Chame esse método para desligar o pool de threads. |
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
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.