CThreadPool Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CThreadPool Class.

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

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.

Public Constructors

NameDescription
CThreadPool::CThreadPoolThe constructor for the thread pool.
CThreadPool::~CThreadPoolThe destructor for the thread pool.

Public Methods

NameDescription
CThreadPool::AddRefImplementation of IUnknown::AddRef.
CThreadPool::GetNumThreadsCall this method to get the number of threads in the pool.
CThreadPool::GetQueueHandleCall this method to get the handle of the IO completion port used to queue work items.
CThreadPool::GetSizeCall this method to get the number of threads in the pool.
CThreadPool::GetTimeoutCall this method to get the maximum time in milliseconds that the thread pool will wait for a thread to shut down.
CThreadPool::InitializeCall this method to initialize the thread pool.
CThreadPool::QueryInterfaceImplementation of IUnknown::QueryInterface.
CThreadPool::QueueRequestCall this method to queue a work item to be handled by a thread in the pool.
CThreadPool::ReleaseImplementation of IUnknown::Release.
CThreadPool::SetSizeCall this method to set the number of threads in the pool.
CThreadPool::SetTimeoutCall this method to set the maximum time in milliseconds that the thread pool will wait for a thread to shut down.
CThreadPool::ShutdownCall 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

IThreadPoolConfig

CThreadPool

Header: atlutil.h

Implementation of IUnknown::AddRef.

ULONG STDMETHODCALLTYPE AddRef() throw();

Return Value

Always returns 1.

Remarks

This class does not implement lifetime control using reference counting.

The constructor for the thread pool.

CThreadPool() throw();

Remarks

Initializes the timeout value to ATLS_DEFAULT_THREADPOOLSHUTDOWNTIMEOUT.

The destructor for the thread pool.

~CThreadPool() throw();

Remarks

Calls CThreadPool::Shutdown.

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.

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.

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.

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.

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.

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.

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.

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.

Implementation of IUnknown::Release.

ULONG STDMETHODCALLTYPE Release() throw();

Return Value

Always returns 1.

Remarks

This class does not implement lifetime control using reference counting.

Call this method to set the number of threads in the pool.

HRESULT STDMETHODCALLTYPE SetSize(int 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.

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.

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 in the constructor.

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();

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.

IThreadPoolConfig Interface
DefaultThreadTraits
Classes

Show: