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 TRUE。 否則，它會 FALSE傳回 。
言論
此例程會執行下列動作：
將定時器設定為非訊號狀態。
如果指定了 DPC，則會將定時器與 DPC 產生關聯。
如果定時器已經作用中，則會取消定時器。
讓定時器變成使用中，並將定時器的時間和期間設定為指定的值。 如果指定的到期時間已經過去，定時器可以立即到期。
KeSetTimerEx 例程類似於 KeSetCoalescableTimer，但不接受 TolerableDelay 參數。 KeSetCoalescableTimerTolerableDelay 參數可讓呼叫者指定定時器週期的容錯。 使用 TolerableDelay = 0 呼叫 KeSetCoalescableTimer，與 呼叫 KeSetTimerEx相同。 在許多情況下，開發人員可以使用呼叫keSetCoalescableTimer 取代對KeSetTimerEx 呼叫，輕鬆地修改現有的驅動程式。
如果兩個 KeSetCoalescableTimer 呼叫指定相同的定時器物件，而第二次呼叫會在針對第一次呼叫指定的 DueTime 到期之前進行，第二次呼叫會隱含地取消第一次呼叫的定時器。 不過，如果第一次呼叫的定時器到期已經啟用 DPC 執行，DPC 可能會在取消定時器之後執行。 第二次呼叫會以新的到期時間取代第一次呼叫的擱置到期時間，並再次啟動定時器。
如果 Period 參數為非零值，定時器為週期性。 針對定期定時器，第一個定時器到期時間會在 DueTime 參數所指示的時間發生。 稍後的到期時間會以 Period所指定的間隔分隔。 如果 期間 = 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 值。 例如，具有 Period = 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 |