CWorkerThread Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CWorkerThread Class on docs.microsoft.com. 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.

System_CAPS_ICON_important.jpg Important

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

NameDescription
WorkerClientEntry

Public Constructors

NameDescription
CWorkerThread::CWorkerThreadThe constructor for the worker thread.
CWorkerThread::~CWorkerThreadThe destructor for the worker thread.

Public Methods

NameDescription
CWorkerThread::AddHandleCall this method to add a waitable object's handle to the list maintained by the worker thread.
CWorkerThread::AddTimerCall this method to add a periodic waitable timer to the list maintained by the worker thread.
CWorkerThread::GetThreadHandleCall this method to get the thread handle of the worker thread.
CWorkerThread::GetThreadIdCall this method to get the thread ID of the worker thread.
CWorkerThread::InitializeCall this method to initialize the worker thread.
CWorkerThread::RemoveHandleCall this method to remove a handle from the list of waitable objects.
CWorkerThread::ShutdownCall this method to shut down the worker thread.

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.

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

Show: