KeSetCoalescableTimer 函数 （wdm.h）
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
指定 时间段 指定的计时器周期的容差（以毫秒为单位），以及 DueTime 指定的初始时间间隔。 对于定期计时器，两个连续计时器过期之间的时间间隔将介于（Period - TolerableDelay） 到 （Period + TolerableDelay） 之间）。 初始到期时间将介于 DueTime 到 （DueTime + TolerableDelay） 范围内。 TolerableDelay 值不能为负值。
[in, optional] Dpc
指向 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 参数指示。 以后的过期时间由 周期指定的时间间隔分隔。 如果 期间 = 0，则计时器为非性能，并在 DueTime指示的时间过期。
如果 Dpc 参数为非NULL，则例程会在指定的 DPC 对象与计时器对象之间创建关联。 计时器过期后，计时器服务将从系统计时器队列中删除计时器对象，并将此对象设置为信号状态。 如果 DPC 对象与计时器对象相关联，计时器服务会将 DPC 对象插入系统 DPC 队列，以便在条件允许后立即运行。
特定 DPC 对象的一个实例一次只能位于系统 DPC 队列中。 为了避免潜在的争用条件，请避免将相同的 DPC 对象传递给 KeSetCoalescableTimer 和 KeInsertQueueDpc 例程。
避免更改与活动计时器关联的 DPC 的重要性或目标处理器。 取消计时器或确保计时器在调用例程（如 KeSetImportanceDpc 或 KeSetTargetProcessorDpcEx）之前已过期，以更改 DPC 设置。 例如，如果驱动程序在计时器使 DPC 能够运行时更新 DPC 的目标处理器，DPC 可能会在任意处理器上运行。
定期计时器在过期后自动重启。 因此，在多处理器系统中，定期计时器的 DPC 可能同时在两个或多个处理器上运行。
驱动程序必须取消其 卸载 例程中的任何活动计时器。 调用 KeCancelTimer 例程以取消计时器。 如果 DPC 与定期或最近可能已过期的计时器相关联，驱动程序必须等待（例如，通过调用 KeFlushQueuedDpcs 例程）释放 DPC 及其关联数据，直到所有处理器上所有挂起的 DPC 执行完成。
KeSetCoalescableTimer 使用 TolerableDelay 参数来执行计时器合并。 也就是说，例程会调整计时器的过期时间，以适应其他软件计时器的到期时间。 计时器合并有助于增加空闲期的长度，以便作系统可以降低能耗并提高能效。
若要有效使用计时器合并，调用方应指定至少 32 毫秒的 TolerableDelay 值。 此值等于 15.6 毫秒的两个默认系统时钟间隔。 如果可以，请使用更大的 TolerableDelay 值，例如 100 毫秒。
尝试以 50 毫秒的倍数指定 Period 和 TolerableDelay 值。 典型的 周期 值为 50、100、250、500 和 1000 毫秒。 典型的 TolerableDelay 值为 50、100、150 和 250 毫秒。
通常，具有较大 周期 值的计时器可以使用比例较大的 TolerableDelay 值。 例如，周期 = 500 毫秒的计时器可能会使用 TolerableDelay = 50 毫秒，但具有 Period = 10 秒的计时器可能会使用 TolerableDelay = 1 秒。
过期时间相对于系统时钟进行度量，以及作系统在计时器过期时可以检测到的准确度受系统时钟粒度的限制。 有关详细信息，请参阅 计时器准确性。
有关计时器对象的详细信息，请参阅 计时器对象和 DPC。 有关计时器合并的详细信息，请参阅 WHDC 网站上的 Windows 计时器合并 白皮书。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | 从 Windows 7 开始可用。 |
| 目标平台 | 普遍 |
| 标头 | wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h） |
| 库 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |