KeSetCoalescableTimer 函数 (wdm.h)

项目
02/27/2024

KeSetCoalescableTimer 例程设置计时器对象的初始过期时间和时间段，并指定在过期时间中可以容忍的延迟量。

语法

BOOLEAN KeSetCoalescableTimer(
  [in, out]      PKTIMER       Timer,
  [in]           LARGE_INTEGER DueTime,
  [in]           ULONG         Period,
  [in]           ULONG         TolerableDelay,
  [in, optional] PKDPC         Dpc
);

参数

[in, out] Timer

指向计时器对象的指针。此参数指向 KTIMER 结构，该结构是表示计时器对象的不透明系统结构。此对象必须以前由 KeInitializeTimerEx 或 KeInitializeTimer 例程初始化。

[in] DueTime

指定计时器过期的绝对时间或相对时间。如果 DueTime 参数的值为负值，则过期时间相对于当前系统时间。否则，过期时间是绝对的。过期时间以系统时间单位表示，间隔为 100 纳秒。绝对过期时间跟踪对系统时钟所做的任何更改。相对过期时间不受系统时钟更改的影响。

[in] Period

指定定期计时器过期之间的间隔（以毫秒为单位）。此参数的值不能超过 MAXLONG。此参数是可选的，可以设置为零，以指示计时器为非持久性。

[in] TolerableDelay

指定 Period 指定的计时器周期的容差（以毫秒为单位），以及 DueTime 指定的初始时间间隔。对于定期计时器，两个连续计时器过期之间的时间间隔范围为从 (期间 - TolerableDelay) 到 (周期 + TolerableDelay) 。初始过期时间的范围是从 DueTime 到 (DueTime + TolerableDelay) 。 TolerableDelay 值不能为负值。

[in, optional] Dpc

指向 DPC 对象的指针。此参数指向 KDPC 结构，它是表示 DPC 对象的不透明系统结构。此对象必须以前由 KeInitializeDpc 例程初始化。此参数是可选的，如果调用方不需要 DPC，则可以指定为 NULL 。

返回值

如果计时器对象已在系统计时器队列中，KeSetCoalescableTimer 将返回 TRUE。否则，它将返回 FALSE。

注解

此例程执行以下操作：

将计时器设置为非信号状态。
如果指定了 DPC，则将计时器与 DPC 相关联。
如果计时器已处于活动状态，则取消计时器。
使计时器处于活动状态，并将计时器的到期时间和时间段设置为指定的值。如果指定的到期时间已过，计时器可能会立即过期。

KeSetTimerEx 例程类似于 KeSetCoalescableTimer，但不接受 TolerableDelay 参数。 KeSetCoalescableTimer 的 TolerableDelay 参数使调用方能够指定计时器周期的容差。调用 TolerableDelay = 0 的 KeSetCoalescableTimer 与调用 KeSetTimerEx 相同。在许多情况下，开发人员可以通过将 对 KeSetTimerEx 的调用替换为对 KeSetCoalescableTimer 的调用来轻松修改现有驱动程序。

如果两个 KeSetCoalescableTimer 调用指定了相同的计时器对象，并且第二次调用发生在为第一次调用指定的 DueTime 到期之前，则第二次调用将隐式取消第一次调用的计时器。但是，如果第一次调用的计时器过期已使 DPC 能够运行，则 DPC 可能会在计时器取消后运行。第二个调用将第一次调用的挂起过期时间替换为新的过期时间，并再次激活计时器。

如果 Period 参数不为零，则计时器是定期的。对于定期计时器，第一个计时器过期发生在 DueTime 参数指示的时间。以后的过期时间按 Period 指定的时间间隔分隔。如果 Period = 0，则计时器为非周期计时器，并在 DueTime 指示的时间过期。

如果 Dpc 参数为非 NULL，则例程会在指定的 DPC 对象和计时器对象之间创建关联。计时器过期后，计时器服务将从系统计时器队列中删除计时器对象，并将此对象设置为信号状态。如果 DPC 对象与计时器对象相关联，则计时器服务会将 DPC 对象插入系统 DPC 队列，以便在条件允许时立即运行。

系统 DPC 队列中一次只能有一个特定 DPC 对象的实例。若要避免潜在的争用情况，请避免将相同的 DPC 对象传递给 KeSetCoalescableTimer 和 KeInsertQueueDpc 例程。

避免更改与活动计时器关联的 DPC 的重要性或目标处理器。在调用例程（如 KeSetImportanceDpc 或 KeSetTargetProcessorDpcEx ）更改 DPC 设置之前，请取消计时器或确保计时器已过期。例如，如果驱动程序更新 DPC 的目标处理器，而计时器允许 DPC 运行，则 DPC 可能在任意处理器上运行。

定期计时器在过期后立即自动重启。因此，在多处理器系统中，定期计时器的 DPC 可能同时在两个或多个处理器上运行。

驱动程序必须取消其 Unload 例程中的任何活动计时器。调用 KeCancelTimer 例程以取消计时器。如果 DPC 与定期计时器相关联或最近可能已过期，驱动程序必须等待 (例如，调用 KeFlushQueuedDpcs 例程) 释放 DPC 及其关联数据，直到所有处理器上所有挂起的 DPC 执行完成。

KeSetCoalescableTimer 使用 TolerableDelay 参数执行计时器合并。也就是说，例程调整计时器的过期时间，以与其他软件计时器的过期时间一致。计时器合并有助于增加空闲时段的长度，以便操作系统可以减少功耗并提高能效。

若要有效地使用计时器合并，调用方应指定至少 32 毫秒的 TolerableDelay 值。此值等于两个默认系统时钟间隔（15.6 毫秒）。如果可以，请使用更大的 TolerableDelay 值，例如 100 毫秒。

尝试以 50 毫秒的倍数指定 Period 和 TolerableDelay 值。典型的 Period 值为 50、100、250、500 和 1000 毫秒。典型的 TolerableDelay 值为 50、100、150 和 250 毫秒。

通常，具有较大 Period 值的计时器可以使用比例较大的 TolerableDelay 值。例如， Period = 500 毫秒的计时器可能使用 TolerableDelay = 50 毫秒，但 Period = 10 秒的计时器可能使用 TolerableDelay = 1 秒。

过期时间相对于系统时钟进行度量，操作系统在计时器过期时可以检测到的准确度受系统时钟粒度的限制。有关详细信息，请参阅计时器准确性。

有关计时器对象的详细信息，请参阅计时器对象和 DPC。有关计时器合并的详细信息，请参阅 WHDC 网站上的 Windows 计时器合并白皮书。

要求

要求	值
最低受支持的客户端	从 Windows 7 开始可用。
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL