KeSetCoalescableTimer 関数 (wdm.h)

[アーティクル]
03/16/2023

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 を超えてはなりません。このパラメーターは省略可能であり、タイマーが非永続であることを示す 0 に設定できます。

[in] TolerableDelay

Period が指定するタイマー期間と DueTime が指定する初期時間間隔の許容範囲をミリ秒単位で指定します。定期的なタイマーの場合、2 つの連続するタイマーの有効期限の時間間隔は、(Period - TolerableDelay) から (Period + TolerableDelay) の範囲になります。最初の有効期限は DueTime から (DueTime + TolerableDelay) までの範囲になります。 TolerableDelay 値を負にすることはできません。

[in, optional] Dpc

DPC オブジェクトへのポインター。このパラメーターは、DPC オブジェクトを表す不透明なシステム構造である KDPC 構造体を指します。このオブジェクトは、以前に KeInitializeDpc ルーチンによって初期化されている必要があります。このパラメーターは省略可能であり、呼び出し元が DPC を必要としない場合は NULL として指定できます。

戻り値

タイマーオブジェクトがシステムタイマーキューに既に存在する場合、KeSetCoalescableTimer は TRUE を返します。それ以外の場合は、 FALSE を返します。

注釈

このルーチンでは、次の処理が行われます。

タイマーを非シグナル状態に設定します。
DPC が指定されている場合は、タイマーを DPC に関連付けます。
タイマーが既にアクティブな場合は、タイマーを取り消します。
タイマーをアクティブにし、タイマーの期限と期間を指定した値に設定します。指定された期限が既に経過している場合、タイマーはすぐに期限切れになる可能性があります。

KeSetTimerEx ルーチンは KeSetCoalescableTimer に似ていますが、TolerableDelay パラメーターは受け入れられません。 KeSetCoalescableTimer の TolerableDelay パラメーターを使用すると、呼び出し元はタイマー期間の許容範囲を指定できます。 TolerableDelay = 0 を使用した KeSetCoalescableTimer の呼び出しは、KeSetTimerEx の呼び出しと同じです。多くの場合、開発者は 、KeSetTimerEx の呼び出しを KeSetCoalescableTimer の呼び出しに置き換えることで、既存のドライバーを簡単に変更できます。

2 つの KeSetCoalescableTimer 呼び出しで同じタイマーオブジェクトを指定し、最初の呼び出しに指定された DueTime の前に 2 番目の呼び出しが発生した場合、2 番目の呼び出しは最初の呼び出しから暗黙的にタイマーを取り消します。ただし、最初の呼び出しからのタイマーの有効期限が既に DPC の実行を有効にしている場合は、タイマーが取り消された後に DPC が実行される可能性があります。 2 番目の呼び出しは、最初の呼び出しからの保留中の有効期限を新しい有効期限に置き換え、タイマーをもう一度アクティブにします。

Period パラメーターが 0 以外の場合、タイマーは定期的です。定期的なタイマーの場合、最初のタイマーの有効期限は DueTime パラメーターで示された時刻に発生します。後の有効期限は、 Period で指定された間隔で区切ります。 Period = 0 の場合、タイマーは非周期であり、DueTime によって示される時点で期限切れになります。

Dpc パラメーターが NULL 以外の場合、ルーチンは指定された DPC オブジェクトとタイマーオブジェクトの間に関連付けを作成します。タイマーの有効期限が切れると、タイマーサービスはシステムタイマーキューからタイマーオブジェクトを削除し、このオブジェクトをシグナル状態に設定します。 DPC オブジェクトがタイマーオブジェクトに関連付けられている場合、タイマーサービスは DPC オブジェクトをシステム DPC キューに挿入して、条件が許可されたらすぐに実行します。

特定の DPC オブジェクトのインスタンスを一度に 1 つだけシステム DPC キューに格納できます。競合状態の可能性を回避するには、同じ DPC オブジェクトを KeSetCoalescableTimer ルーチンと KeInsertQueueDpc ルーチンの両方に渡さないようにします。

アクティブタイマーに関連付けられている DPC の重要度またはターゲットプロセッサを変更しないでください。タイマーを取り消すか、 KeSetImportanceDpc や KeSetTargetProcessorDpcEx などのルーチンを呼び出して DPC 設定を変更する前に、タイマーの有効期限が切れたことを確認します。たとえば、ドライバーが DPC のターゲットプロセッサを更新し、タイマーによって DPC の実行が有効になっている場合、DPC は任意のプロセッサで実行される可能性があります。

定期的なタイマーは、有効期限が切れるとすぐに自動的に再起動します。したがって、マルチプロセッサシステムでは、定期的なタイマーの DPC が 2 つ以上のプロセッサで同時に実行されている可能性があります。

ドライバーは、アンロードルーチンでアクティブなタイマーを取り消す必要があります。 KeCancelTimer ルーチンを呼び出してタイマーを取り消します。 DPC が定期的なタイマーに関連付けられている場合、または最近期限切れになった可能性がある場合、ドライバーは (たとえば、KeFlushQueuedDpcs ルーチンを呼び出すことによって) 待機して、すべてのプロセッサで保留中のすべての DPC 実行が完了するまで DPC とそれに関連付けられたデータを解放する必要があります。

KeSetCoalescableTimer は 、TolerableDelay パラメーターを使用してタイマー結合を実行します。つまり、ルーチンは、タイマーが他のソフトウェアタイマーの有効期限と一致するように有効期限を調整します。タイマー合体は、オペレーティングシステムが電力消費を削減し、エネルギー効率を向上できるように、アイドル期間の長さを増やすのに役立ちます。

タイマー結合を効果的に使用するには、呼び出し元で TolerableDelay 値を 32 ミリ秒以上指定する必要があります。この値は、15.6 ミリ秒の 2 つの既定のシステムクロック間隔と等しくなります。可能な場合は、100 ミリ秒など、より大きな TolerableDelay 値を使用します。

Period と TolerableDelay の値を 50 ミリ秒の倍数で指定してみてください。一般的な期間の値は、50、100、250、500、1000 ミリ秒です。 一般的な TolerableDelay 値は、50、100、150、250 ミリ秒です。

通常、 Period 値が大きいタイマーでは、比例して大きな TolerableDelay 値を 使用できます。たとえば、 Period = 500 ミリ秒のタイマーでは TolerableDelay = 50 ミリ秒を使用できますが、 Period = 10 秒のタイマーでは TolerableDelay = 1 秒を使用できます。

有効期限はシステムクロックに対して測定され、オペレーティングシステムがタイマーの有効期限を検出できる精度は、システムクロックの粒度によって制限されます。詳細については、「タイマーの精度」を参照してください。

タイマーオブジェクトの詳細については、「タイマーオブジェクトと DPC」を参照してください。タイマー結合の詳細については、WHDC Web サイトの Windows タイマー結合に関するホワイトペーパーを参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 7 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL