CThreadPool Class
This class provides a pool of worker threads that process a queue of work items.
Syntax
template <class Worker, class ThreadTraits = DefaultThreadTraits>
class CThreadPool : public IThreadPoolConfig
Parameters
Worker
The class conforming to the worker archetype providing the code used to process work items queued on the thread pool.
ThreadTraits
The class providing the function used to create the threads in the pool.
Members
Public Constructors
| Name | Description |
|---|---|
| CThreadPool::CThreadPool | The constructor for the thread pool. |
| CThreadPool::~CThreadPool | The destructor for the thread pool. |
Public Methods
| Name | Description |
|---|---|
| CThreadPool::AddRef | Implementation of IUnknown::AddRef. |
| CThreadPool::GetNumThreads | Call this method to get the number of threads in the pool. |
| CThreadPool::GetQueueHandle | Call this method to get the handle of the IO completion port used to queue work items. |
| CThreadPool::GetSize | Call this method to get the number of threads in the pool. |
| CThreadPool::GetTimeout | Call this method to get the maximum time in milliseconds that the thread pool will wait for a thread to shut down. |
| CThreadPool::Initialize | Call this method to initialize the thread pool. |
| CThreadPool::QueryInterface | Implementation of IUnknown::QueryInterface. |
| CThreadPool::QueueRequest | Call this method to queue a work item to be handled by a thread in the pool. |
| CThreadPool::Release | Implementation of IUnknown::Release. |
| CThreadPool::SetSize | Call this method to set the number of threads in the pool. |
| CThreadPool::SetTimeout | Call this method to set the maximum time in milliseconds that the thread pool will wait for a thread to shut down. |
| CThreadPool::Shutdown | Call this method to shut down the thread pool. |
Remarks
Threads in the pool are created and destroyed when the pool is initialized, resized, or shut down. An instance of class Worker will be created on the stack of each worker thread in the pool. Each instance will live for the lifetime of the thread.
Immediately after creation of a thread, Worker::Initialize will be called on the object associated with that thread. Immediately before destruction of a thread, Worker::Terminate will be called. Both methods must accept a void* argument. The value of this argument is passed to the thread pool through the pvWorkerParam parameter of CThreadPool::Initialize.
When there are work items in the queue and worker threads available for work, a worker thread will pull an item off the queue and call the Execute method of the Worker object for that thread. Three items are then passed to the method: the item from the queue, the same pvWorkerParam passed to Worker:: Initialize and Worker:: Terminate, and a pointer to the OVERLAPPED structure used for the IO completion port queue.
The Worker class declares the type of the items that will be queued on the thread pool by providing a typedef, Worker:: RequestType. This type must be capable of being cast to and from a ULONG_PTR.
An example of a Worker class is CNonStatelessWorker Class.
Inheritance Hierarchy
IUnknown
CThreadPool
Requirements
Header: atlutil.h
CThreadPool::AddRef
Implementation of IUnknown::AddRef.
ULONG STDMETHODCALLTYPE AddRef() throw();
Return Value
Always returns 1.
Remarks
This class does not implement lifetime control using reference counting.
CThreadPool::CThreadPool
The constructor for the thread pool.
CThreadPool() throw();
Remarks
Initializes the timeout value to ATLS_DEFAULT_THREADPOOLSHUTDOWNTIMEOUT. The default time is 36 seconds. If necessary, you can define your own positive integer value for this symbol before including atlutil.h.
CThreadPool::~CThreadPool
The destructor for the thread pool.
~CThreadPool() throw();
Remarks
Calls CThreadPool::Shutdown.
CThreadPool::GetNumThreads
Call this method to get the number of threads in the pool.
int GetNumThreads() throw();
Return Value
Returns the number of threads in the pool.
CThreadPool::GetQueueHandle
Call this method to get the handle of the IO completion port used to queue work items.
HANDLE GetQueueHandle() throw();
Return Value
Returns the queue handle or NULL if the thread pool has not been initialized.
CThreadPool::GetSize
Call this method to get the number of threads in the pool.
HRESULT STDMETHODCALLTYPE GetSize(int* pnNumThreads) throw();
Parameters
pnNumThreads
[out] Address of the variable that, on success, receives the number of threads in the pool.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
CThreadPool::GetTimeout
Call this method to get the maximum time in milliseconds that the thread pool will wait for a thread to shut down.
HRESULT STDMETHODCALLTYPE GetTimeout(DWORD* pdwMaxWait) throw();
Parameters
pdwMaxWait
[out] Address of the variable that, on success, receives the maximum time in milliseconds that the thread pool will wait for a thread to shut down.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
This timeout value is used by CThreadPool::Shutdown if no other value is supplied to that method.
CThreadPool::Initialize
Call this method to initialize the thread pool.
HRESULT Initialize(
void* pvWorkerParam = NULL,
int nNumThreads = 0,
DWORD dwStackSize = 0,
HANDLE hCompletion = INVALID_HANDLE_VALUE) throw();
Parameters
pvWorkerParam
The worker parameter to be passed to the worker thread object's Initialize, Execute, and Terminate methods.
nNumThreads
The requested number of threads in the pool.
If nNumThreads is negative, its absolute value will be multiplied by the number of processors in the machine to get the total number of threads.
If nNumThreads is zero, ATLS_DEFAULT_THREADSPERPROC will be multiplied by the number of processors in the machine to get the total number of threads. The default is 2 threads per processor. If necessary, you can define your own positive integer value for this symbol before including atlutil.h.
dwStackSize
The stack size for each thread in the pool.
hCompletion
The handle of an object to associate with the completion port.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
CThreadPool::QueryInterface
Implementation of IUnknown::QueryInterface.
HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void** ppv) throw();
Remarks
Objects of this class can be successfully queried for the IUnknown and IThreadPoolConfig interfaces.
CThreadPool::QueueRequest
Call this method to queue a work item to be handled by a thread in the pool.
BOOL QueueRequest(Worker::RequestType request) throw();
Parameters
request
The request to be queued.
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
This method adds a work item to the queue. The threads in the pool pick items off the queue in the order in which they are received.
CThreadPool::Release
Implementation of IUnknown::Release.
ULONG STDMETHODCALLTYPE Release() throw();
Return Value
Always returns 1.
Remarks
This class does not implement lifetime control using reference counting.
CThreadPool::SetSize
Call this method to set the number of threads in the pool.
HRESULT STDMETHODCALLTYPE SetSizeint nNumThreads) throw();
Parameters
nNumThreads
The requested number of threads in the pool.
If nNumThreads is negative, its absolute value will be multiplied by the number of processors in the machine to get the total number of threads.
If nNumThreads is zero, ATLS_DEFAULT_THREADSPERPROC will be multiplied by the number of processors in the machine to get the total number of threads. The default is 2 threads per processor. If necessary, you can define your own positive integer value for this symbol before including atlutil.h.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
If the number of threads specified is less than the number of threads currently in the pool, the object puts a shutdown message on the queue to be picked up by a waiting thread. When a waiting thread pulls the message off the queue, it notifies the thread pool and exits the thread procedure. This process is repeated until the number of threads in the pool reaches the specified number or until no thread has exited within the period specified by GetTimeout/ SetTimeout. In this situation the method will return an HRESULT corresponding to WAIT_TIMEOUT and the pending shutdown message is canceled.
CThreadPool::SetTimeout
Call this method to set the maximum time in milliseconds that the thread pool will wait for a thread to shut down.
HRESULT STDMETHODCALLTYPE SetTimeout(DWORD dwMaxWait) throw();
Parameters
dwMaxWait
The requested maximum time in milliseconds that the thread pool will wait for a thread to shut down.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
The timeout is initialized to ATLS_DEFAULT_THREADPOOLSHUTDOWNTIMEOUT. The default time is 36 seconds. If necessary, you can define your own positive integer value for this symbol before including atlutil.h.
Note that dwMaxWait is the time that the pool will wait for a single thread to shut down. The maximum time that could be taken to remove multiple threads from the pool could be slightly less than dwMaxWait multiplied by the number of threads.
CThreadPool::Shutdown
Call this method to shut down the thread pool.
void Shutdown(DWORD dwMaxWait = 0) throw();
Parameters
dwMaxWait
The requested maximum time in milliseconds that the thread pool will wait for a thread to shut down. If 0 or no value is supplied, this method will use the timeout set by CThreadPool::SetTimeout.
Remarks
This method posts a shutdown request to all threads in the pool. If the timeout expires, this method will call TerminateThread on any thread that did not exit. This method is called automatically from the destructor of the class.