createTimerQueueTimer 函数 (threadpoollegacyapiset.h)

  • 项目

创建计时器队列计时器。 此计时器在指定的到期时间过期，然后在每个指定的时间段后过期。 计时器过期时，将调用回调函数。

语法

BOOL CreateTimerQueueTimer(
  [out]          PHANDLE             phNewTimer,
  [in, optional] HANDLE              TimerQueue,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Parameter,
  [in]           DWORD               DueTime,
  [in]           DWORD               Period,
  [in]           ULONG               Flags
);

参数

[out] phNewTimer

指向缓冲区的指针，该缓冲区在返回时接收计时器队列计时器的句柄。 如果此句柄已过期且不再需要，请通过调用 DeleteTimerQueueTimer 将其释放。

[in, optional] TimerQueue

计时器队列的句柄。 此句柄由 CreateTimerQueue 函数返回。

如果此参数为 NULL，则计时器与默认计时器队列相关联。

[in] Callback

指向在计时器过期时要执行的 WAITORTIMERCALLBACK 类型的应用程序定义函数的指针。 有关详细信息，请参阅 WaitOrTimerCallback。

[in, optional] Parameter

将传递给回调函数的单个参数值。

[in] DueTime

相对于第一次向计时器发出信号之前必须经过的当前时间的时间量（以毫秒为单位）。

[in] Period

计时器的时间段（以毫秒为单位）。 如果此参数为零，则计时器将发出一次信号。 如果此参数大于零，则计时器是定期的。 定期计时器会在该时间段过后自动重新激活，直到计时器被取消。

[in] Flags

此参数可以是 WinNT.h 中的以下一个或多个值。

值 含义
WT_EXECUTEDEFAULT
0x00000000
 默认情况下，回调函数将排队到非 I/O 工作线程。
WT_EXECUTEINTIMERTHREAD
0x00000020
 回调函数由计时器线程本身调用。 此标志应仅用于短任务，否则可能会影响其他计时器操作。

回调函数作为 APC 排队。 它不应执行可发出警报的等待操作。
WT_EXECUTEINIOTHREAD
0x00000001
 未使用此标志。

Windows Server 2003 和 Windows XP： 回调函数将排队到 I/O 工作线程。 如果应在处于可警报状态等待的线程中执行函数，则应使用此标志。

从 Windows Vista 和 Windows Server 2008 开始删除 I/O 工作线程。
WT_EXECUTEINPERSISTENTTHREAD
0x00000080
 回调函数将排队到永不终止的线程。 它不保证每次都使用相同的线程。 此标志应仅用于短任务，否则可能会影响其他计时器操作。

如果线程调用使用 APC 的函数，则必须设置此标志。 有关详细信息，请参阅 异步过程调用。

请注意，目前没有真正持久的工作线程，但如果有任何挂起的 I/O 请求，则不会终止任何工作线程。
WT_EXECUTELONGFUNCTION
0x00000010
 回调函数可以执行长时间的等待。 此标志可帮助系统决定是否应创建新线程。
WT_EXECUTEONLYONCE
0x00000008
 计时器将仅设置为信号状态一次。 如果设置了此标志，则 Period 参数必须为零。
WT_TRANSFER_IMPERSONATION
0x00000100
 回调函数将使用当前访问令牌，无论是进程令牌还是模拟令牌。 如果未指定此标志，则回调函数仅使用进程令牌执行。

Windowsxp： 在 Windows XP SP2 和 Windows Server 2003 之前，不支持此标志。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。

注解

如果 DueTime 和 Period 参数均为非零值，则计时器将首先在到期时间发出信号，然后定期发出信号。 每次经过该时间段时都会调用回调，无论上一个回调是否已完成执行。 回调函数将排队到线程池。 这些线程会受到计划延迟的影响，因此时间可能会有所不同，具体取决于应用程序或系统中发生的其他情况。

系统在睡眠或休眠中花费的时间不计入计时器的过期时间。 当系统处于唤醒状态的累计已用时间量与计时器的到期时间或时间段匹配时，将发出计时器信号。

Windows Server 2003 和 Windows XP： 系统处于睡眠或休眠状态的时间计入计时器到期时间。 如果计时器在系统处于睡眠状态时过期，则会在系统唤醒时立即发出该计时器的信号。

若要取消计时器，请调用 DeleteTimerQueueTimer 函数。 若要取消计时器队列中的所有计时器，请调用 DeleteTimerQueueEx 函数。

默认情况下，线程池最多有 500 个线程。 若要提高此限制，请使用 WinNT.h 中定义的 WT_SET_MAX_THREADPOOL_THREAD 宏。

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

指定 Flags 参数时使用此宏。 宏参数是所需的标志，新限制 (最多 (2<<16) -1 线程) 。 但请注意，应用程序可以通过保持较低的工作线程数来提高其性能。

若要编译使用此函数的应用程序， 请将_WIN32_WINNT 定义为 0x0500 或更高版本。 有关详细信息，请参阅 使用 Windows 标头。

示例

有关使用 CreateTimerQueueTimer 的示例，请参阅 使用计时器队列。

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 threadpoollegacyapiset.h
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

CreateTimerQueue

DeleteTimerQueueEx

DeleteTimerQueueTimer

同步函数

线程池

计时器队列