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
針對 Period 所指定的定時器期間，以及 DueTime 所指定的初始時間間隔，指定容錯，以毫秒為單位。 對於定期定時器，兩個連續定時器到期之間的時間間隔介於 (Period - TolerableDelay) 到 (Period + 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 相同。 在許多情況下，開發人員可以使用對KeSetCoalescableTimer的呼叫來取代KeSetTimerEx的呼叫，輕鬆地修改現有的驅動程式。
如果兩個 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 開始提供。 |
| 目標平台 | Universal |
| 標頭 | wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |