| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CWorkerThread Class |
CWorkerThread Class |
11/04/2016 |
|
|
be79a832-1345-4a36-a13e-a406cc65286f |
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.
template <class ThreadTraits = DefaultThreadTraits>
class CWorkerThread
ThreadTraits
The class providing the thread creation function, such as CRTThreadTraits or Win32ThreadTraits.
| Name | Description |
|---|---|
WorkerClientEntry |
| Name | Description |
|---|---|
| CWorkerThread::CWorkerThread | The constructor for the worker thread. |
| CWorkerThread::~CWorkerThread | The destructor for the worker thread. |
| 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. |
-
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();
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.
Returns S_OK on success, or an error HRESULT on failure.
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();
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.
Returns S_OK on success, or an error HRESULT on failure.
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();
Calls CWorkerThread::Shutdown.
Call this method to get the thread handle of the worker thread.
HANDLE GetThreadHandle() throw();
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();
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();
pThread
An existing worker thread.
Returns S_OK on success, or an error HRESULT on failure.
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();
hObject
The handle to remove.
Returns S_OK on success, or an error HRESULT on failure.
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();
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.
Returns S_OK on success, or an error HRESULT on failure, such as if the timeout value, dwWait, is exceeded.
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