CWorkerThread 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 CWorkerThread Class.
This class creates a worker thread or uses an existing one, waits on one or more kernel object handles, and executes a specified client function when one of the handles is signaled.
This class and its members cannot be used in applications that execute in the Windows Runtime. |
template <class ThreadTraits = DefaultThreadTraits> class CWorkerThread
Parameters
ThreadTraits
The class providing the thread creation function, such as CRTThreadTraits or Win32ThreadTraits.
Protected Structures
| Name | Description |
|---|---|
WorkerClientEntry |
Public Constructors
| Name | Description |
|---|---|
| CWorkerThread::CWorkerThread | The constructor for the worker thread. |
| CWorkerThread::~CWorkerThread | The destructor for the worker thread. |
Public Methods
| Name | Description |
|---|---|
| CWorkerThread::AddHandle | Call this method to add a waitable object's handle to the list maintained by the worker thread. |
| CWorkerThread::AddTimer | Call this method to add a periodic waitable timer to the list maintained by the worker thread. |
| CWorkerThread::GetThreadHandle | Call this method to get the thread handle of the worker thread. |
| CWorkerThread::GetThreadId | Call this method to get the thread ID of the worker thread. |
| CWorkerThread::Initialize | Call this method to initialize the worker thread. |
| CWorkerThread::RemoveHandle | Call this method to remove a handle from the list of waitable objects. |
| CWorkerThread::Shutdown | Call this method to shut down the worker thread. |
To use CWorkerThread
Create an instance of this class.
Call CWorkerThread::AddHandle with the handle of a kernel object and a pointer to an implementation of IWorkerThreadClient.
– or –
Call CWorkerThread::AddTimer with a pointer to an implementation of IWorkerThreadClient.
Implement IWorkerThreadClient::Execute to take some action when the handle or timer is signaled.
To remove an object from the list of waitable objects, call CWorkerThread::RemoveHandle.
To terminate the thread, call CWorkerThread::Shutdown.
Header: atlutil.h
Call this method to add a waitable object's handle to the list maintained by the worker thread.
HRESULT AddHandle(
HANDLE hObject,
IWorkerThreadClient* pClient,
DWORD_PTR dwParam) throw();
Parameters
hObject
The handle to a waitable object.
pClient
The pointer to the IWorkerThreadClient interface on the object to be called when the handle is signaled.
dwParam
The parameter to be passed to IWorkerThreadClient::Execute when the handle is signaled.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
IWorkerThreadClient::Execute will be called through pClient when the handle, hObject, is signaled.
Call this method to add a periodic waitable timer to the list maintained by the worker thread.
HRESULT AddTimer(
DWORD dwInterval,
IWorkerThreadClient* pClient,
DWORD_PTR dwParam,
HANDLE* phTimer) throw();
Parameters
dwInterval
Specifies the period of the timer in milliseconds.
pClient
The pointer to the IWorkerThreadClient interface on the object to be called when the handle is signaled.
dwParam
The parameter to be passed to IWorkerThreadClient::Execute when the handle is signaled.
phTimer
[out] Address of the HANDLE variable that, on success, receives the handle to the newly created timer.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
IWorkerThreadClient::Execute will be called through pClient when the timer is signaled.
Pass the timer handle from phTimer to CWorkerThread::RemoveHandle to close the timer.
The constructor.
CWorkerThread() throw();
The destructor.
~CWorkerThread() throw();
Remarks
Calls CWorkerThread::Shutdown.
Call this method to get the thread handle of the worker thread.
HANDLE GetThreadHandle() throw();
Return Value
Returns the thread handle or NULL if the worker thread has not been initialized.
Call this method to get the thread ID of the worker thread.
DWORD GetThreadId() throw();
Return Value
Returns the thread ID or NULL if the worker thread has not been initialized.
Call this method to initialize the worker thread.
HRESULT Initialize() throw(); HRESULT Initialize(CWorkerThread<ThreadTraits>* pThread) throw();
Parameters
pThread
An existing worker thread.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
This method should be called to initialize the object after creation or after a call to CWorkerThread::Shutdown.
To have two or more CWorkerThread objects use the same worker thread, initialize one of them without passing any arguments then pass a pointer to that object to the Initialize methods of the others. The objects initialized using the pointer should be shut down before the object used to initialize them.
See CWorkerThread::Shutdown for information on how that method's behavior changes when initialized using a pointer to an existing object.
Call this method to remove a handle from the list of waitable objects.
HRESULT RemoveHandle(HANDLE hObject) throw();
Parameters
hObject
The handle to remove.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
When the handle is removed IWorkerThreadClient::CloseHandle will be called on the associated object that was passed to AddHandle. If this call fails, CWorkerThread will call the Windows CloseHandle function on the handle.
Call this method to shut down the worker thread.
HRESULT Shutdown(DWORD dwWait = ATL_WORKER_THREAD_WAIT) throw();
Parameters
dwWait
The time in milliseconds to wait for the worker thread to shut down.
Return Value
Returns S_OK on success, or an error HRESULT on failure, such as if the timeout value, dwWait, is exceeded.
Remarks
To reuse the object, call CWorkerThread::Initialize after calling this method.
Note that calling Shutdown on an object initialized with a pointer to another CWorkerThread object has no effect and always returns S_OK.
DefaultThreadTraits
Classes
Multithreading: Creating Worker Threads
IWorkerThreadClient Interface