Edit

CWorkerThread Class

  • Article

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.

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

Syntax

template <class ThreadTraits = DefaultThreadTraits>
class CWorkerThread

Parameters

ThreadTraits
The class providing the thread creation function, such as CRTThreadTraits or Win32ThreadTraits.

Members

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.

Remarks

To use CWorkerThread

  1. Create an instance of this class.

  2. Call CWorkerThread::Initialize.

  3. 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.

  4. Implement IWorkerThreadClient::Execute to take some action when the handle or timer is signaled.

  5. To remove an object from the list of waitable objects, call CWorkerThread::RemoveHandle.

  6. To terminate the thread, call CWorkerThread::Shutdown.

Requirements

Header: atlutil.h

CWorkerThread::AddHandle

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.

CWorkerThread::AddTimer

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.

CWorkerThread::CWorkerThread

The constructor.

CWorkerThread() throw();

CWorkerThread::~CWorkerThread

The destructor.

~CWorkerThread() throw();

Remarks

Calls CWorkerThread::Shutdown.

CWorkerThread::GetThreadHandle

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.

CWorkerThread::GetThreadId

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.

CWorkerThread::Initialize

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.

CWorkerThread::RemoveHandle

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.

CWorkerThread::Shutdown

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. ATL_WORKER_THREAD_WAIT defaults to 10 seconds. If necessary, you can define your own value for this symbol before including atlutil.h.

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.

See also

DefaultThreadTraits
Classes
Multithreading: Creating Worker Threads
IWorkerThreadClient Interface