CWorkerThread 类

  • 项目

此类创建工作线程或使用现有线程，等待一个或多个内核对象句柄，并在发出某个句柄的信号时执行指定的客户端函数。

重要

无法在 Windows 运行时中执行的应用程序中使用此类及其成员。

语法

template <class ThreadTraits = DefaultThreadTraits>
class CWorkerThread

参数

ThreadTraits
类，提供线程创建函数（如 CRTThreadTraits 或 Win32ThreadTraits）。

成员

受保护的结构

名称 描述
WorkerClientEntry

公共构造函数

名称 描述
CWorkerThread::CWorkerThread 工作线程的构造函数。
CWorkerThread::~CWorkerThread 工作线程的析构函数。

公共方法

名称 描述
CWorkerThread::AddHandle 调用此方法可向工作线程维护的列表添加可等待对象的句柄。
CWorkerThread::AddTimer 调用此方法可向工作线程维护的列表添加定期可等待计时器。
CWorkerThread::GetThreadHandle 调用此方法可获取工作线程的线程句柄。
CWorkerThread::GetThreadId 调用此方法可获取工作线程的线程 ID。
CWorkerThread::Initialize 调用此方法可初始化工作线程。
CWorkerThread::RemoveHandle 调用此方法可从可等待对象的列表中删除句柄。
CWorkerThread::Shutdown 调用此方法可关闭工作线程。

注解

使用 CWorkerThread 的步骤

  1. 常见此类的实例。

  2. 调用 CWorkerThread::Initialize。

  3. 使用内核对象的句柄和指向 IWorkerThreadClient 实现的指针调用 CWorkerThread::AddHandle。

    - 或 -

    使用指向 IWorkerThreadClient 实现的指针调用 CWorkerThread::AddTimer。

  4. 实现 IWorkerThreadClient::Execute 以在句柄或计时器收到信号时执行一些操作。

  5. 若要从可等待对象的列表中删除对象，请调用 CWorkerThread::RemoveHandle。

  6. 若要终止线程，请调用 CWorkerThread::Shutdown。

要求

标头：atlutil.h

CWorkerThread::AddHandle

调用此方法可向工作线程维护的列表添加可等待对象的句柄。

HRESULT AddHandle(
    HANDLE hObject,
    IWorkerThreadClient* pClient,
    DWORD_PTR dwParam) throw();

参数

hObject
可等待对象的句柄。

pClient
指向要在句柄收到信号时调用的对象上的 IWorkerThreadClient 接口的指针。

dwParam
要在句柄收到信号时传递给 IWorkerThreadClient::Execute 的参数。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

注解

将在句柄 hObject 收到信号时通过 pClient 调用 IWorkerThreadClient::Execute。

CWorkerThread::AddTimer

调用此方法可向工作线程维护的列表添加定期可等待计时器。

HRESULT AddTimer(
    DWORD dwInterval,
    IWorkerThreadClient* pClient,
    DWORD_PTR dwParam,
    HANDLE* phTimer) throw();

参数

dwInterval
指定计时器的时间段（以毫秒为单位）。

pClient
指向要在句柄收到信号时调用的对象上的 IWorkerThreadClient 接口的指针。

dwParam
要在句柄收到信号时传递给 IWorkerThreadClient::Execute 的参数。

phTimer
[out] HANDLE 变量的地址，在成功时接收新创建的计时器的句柄。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

注解

将在计时器收到信号时通过 pClient 调用 IWorkerThreadClient::Execute。

将计时器句柄从 phTimer 传递到 CWorkerThread::RemoveHandle 以关闭计时器。

CWorkerThread::CWorkerThread

构造函数。

CWorkerThread() throw();

CWorkerThread::~CWorkerThread

析构函数。

~CWorkerThread() throw();

备注

调用 CWorkerThread::Shutdown。

CWorkerThread::GetThreadHandle

调用此方法可获取工作线程的线程句柄。

HANDLE GetThreadHandle() throw();

返回值

如果工作线程尚未初始化，则返回线程句柄或 NULL。

CWorkerThread::GetThreadId

调用此方法可获取工作线程的线程 ID。

DWORD GetThreadId() throw();

返回值

如果工作线程尚未初始化，则返回线程 ID 或 NULL。

CWorkerThread::Initialize

调用此方法可初始化工作线程。

HRESULT Initialize() throw();

HRESULT Initialize(CWorkerThread<ThreadTraits>* pThread) throw();

参数

pThread
现有工作线程。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

注解

应在创建对象或调用 CWorkerThread::Shutdown 之后调用此方法来初始化对象。

若要让两个或多个 CWorkerThread 对象使用同一工作线程，请初始化其中一个对象，无需传递任何参数，然后将指向该对象的指针传递给其他对象的 Initialize 方法。 使用指针进行初始化的对象应在用于初始化它们的对象之前关闭。

若要了解使用指向现有对象的指针进行初始化时该方法的行为如何变化，请参阅 CWorkerThread::Shutdown。

CWorkerThread::RemoveHandle

调用此方法可从可等待对象的列表中删除句柄。

HRESULT RemoveHandle(HANDLE hObject) throw();

参数

hObject
要删除的句柄。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

备注

删除句柄后，将在已传递给 AddHandle 的关联对象上调用 IWorkerThreadClient::CloseHandle。 如果此调用失败，CWorkerThread 将在句柄上调用 Windows CloseHandle 函数。

CWorkerThread::Shutdown

调用此方法可关闭工作线程。

HRESULT Shutdown(DWORD dwWait = ATL_WORKER_THREAD_WAIT) throw();

参数

dwWait
等待工作线程关闭的时间（以毫秒为单位）。 ATL_WORKER_THREAD_WAIT 默认为 10 秒。 如有必要，你可以在包括 atlutil.h 之前为此符号定义你自己的值。

返回值

如果成功，则返回 S_OK；如果失败（例如超过超时值 dwWait），则返回错误 HRESULT。

注解

若要重用对象，请在调用此方法后调用 CWorkerThread::Initialize。

请注意，在一个使用指针（指向另一个 CWorkerThread 对象）进行初始化的对象上调用 Shutdown 没有效果，始终返回 S_OK。

另请参阅

DefaultThreadTraits
类
多线程处理：创建辅助线程
IWorkerThreadClient 接口