| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CThreadPool Class |
CThreadPool Class |
11/04/2016 |
|
|
06683718-01b9-413c-9481-2dc1734ec70f |
This class provides a pool of worker threads that process a queue of work items.
template <class Worker, class ThreadTraits = DefaultThreadTraits>
class CThreadPool : public IThreadPoolConfig
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.
| Name | Description |
|---|---|
| CThreadPool::CThreadPool | The constructor for the thread pool. |
| CThreadPool::~CThreadPool | The destructor for the thread pool. |
| 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. |
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.
IUnknown
CThreadPool
Header: atlutil.h
Implementation of IUnknown::AddRef.
ULONG STDMETHODCALLTYPE AddRef() throw();
Always returns 1.
This class does not implement lifetime control using reference counting.
The constructor for the thread pool.
CThreadPool() throw();
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.
The destructor for the thread pool.
~CThreadPool() throw();
Calls CThreadPool::Shutdown.
Call this method to get the number of threads in the pool.
int GetNumThreads() throw();
Returns the number of threads in the pool.
Call this method to get the handle of the IO completion port used to queue work items.
HANDLE GetQueueHandle() throw();
Returns the queue handle or NULL if the thread pool has not been initialized.
Call this method to get the number of threads in the pool.
HRESULT STDMETHODCALLTYPE GetSize(int* pnNumThreads) throw();
pnNumThreads
[out] Address of the variable that, on success, receives the number of threads in the pool.
Returns S_OK on success, or an error HRESULT on failure.
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();
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.
Returns S_OK on success, or an error HRESULT on failure.
This timeout value is used by CThreadPool::Shutdown if no other value is supplied to that method.
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();
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.
Returns S_OK on success, or an error HRESULT on failure.
Implementation of IUnknown::QueryInterface.
HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void** ppv) throw();
Objects of this class can be successfully queried for the IUnknown and IThreadPoolConfig interfaces.
Call this method to queue a work item to be handled by a thread in the pool.
BOOL QueueRequest(Worker::RequestType request) throw();
request
The request to be queued.
Returns TRUE on success, FALSE on failure.
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.
Implementation of IUnknown::Release.
ULONG STDMETHODCALLTYPE Release() throw();
Always returns 1.
This class does not implement lifetime control using reference counting.
Call this method to set the number of threads in the pool.
HRESULT STDMETHODCALLTYPE SetSizeint nNumThreads) throw();
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.
Returns S_OK on success, or an error HRESULT on failure.
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.
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();
dwMaxWait
The requested maximum time in milliseconds that the thread pool will wait for a thread to shut down.
Returns S_OK on success, or an error HRESULT on failure.
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.
Call this method to shut down the thread pool.
void Shutdown(DWORD dwMaxWait = 0) throw();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.
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.