KeWaitForSingleObject 関数 (wdm.h)

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

KeWaitForSingleObject ルーチンは、指定されたディスパッチャーオブジェクトがシグナル状態または (必要に応じて) 待機がタイムアウトするまで、現在のスレッドを待機状態にします。

構文

NTSTATUS
KeWaitForSingleObject (
    PVOID Object,
    KWAIT_REASON WaitReason,
    KPROCESSOR_MODE WaitMode,
    BOOLEAN Alertable,
    PLARGE_INTEGER Timeout
    );

パラメーター

[in] Object

呼び出し元がストレージを提供する初期化されたディスパッチャーオブジェクト (イベント、ミューテックス、セマフォ、スレッド、タイマー) へのポインター。ディスパッチャーオブジェクトは、非ページシステムメモリに存在する必要があります。詳細については、「解説」を参照してください。

[in] WaitReason

待機の理由を指定します。ドライバーは、ユーザーの代わりに作業を行っていて、ユーザースレッドのコンテキストで実行されている場合を除き、この値を Executive に設定する必要があります。その場合は、この値を UserRequest に設定する必要があります。

[in] WaitMode

呼び出し元が KernelMode または UserMode で待機するかどうかを指定 します。最下位レベルのドライバーと中間ドライバーでは 、KernelMode を指定する必要があります。指定した Object がミューテックスの場合、呼び出し元は KernelMode を指定する必要があります。

[in] Alertable

待機が警告可能な場合は TRUE 、それ以外の場合は FALSE であるブール値を指定します。

[in, optional] Timeout

待機が完了する 100 ナノ秒単位の絶対時間または相対時間を指定するタイムアウト値へのポインター。

正の値は、1601 年 1 月 1 日を基準とした絶対時間を指定します。負の値は、現在の時刻を基準とした間隔を指定します。絶対有効期限は、システム時刻の変更を追跡します。相対有効期限は、システム時間の変更の影響を受けません。

Timeout = 0 の場合、ルーチンは待機せずにを返します。呼び出し元が NULL ポインターを提供する場合、ディスパッチャーオブジェクトがシグナル状態に設定されるまで、ルーチンは無期限に待機します。詳細については、「解説」を参照してください。

戻り値

KeWaitForSingleObject は、次のいずれかを返すことができます。

NT_SUCCESS マクロは、これらすべての状態値を "success" 値として認識します。

リターンコード	説明
STATUS_SUCCESS	Object パラメーターで指定されたディスパッチャーオブジェクトが待機を満たしました。
STATUS_ALERTED	呼び出し元のスレッドにアラートを配信するための待機が中断されました。
STATUS_USER_APC	ユーザー非同期プロシージャ呼び出し (APC) を呼び出し元スレッドに配信するための待機が中断されました。
STATUS_TIMEOUT	オブジェクトがシグナル状態に設定される前にタイムアウトが発生しました。この値は、指定した待機条件のセットをすぐに満たすことができないときに、Timeout が 0 に設定されている場合に返すことができます。

注釈

指定した Object の現在の状態を調べて、待機をすぐに満たすことができるかどうかを判断します。その場合、必要な副作用がオブジェクトに対して実行されます。それ以外の場合、現在のスレッドは待機状態になり、現在のプロセッサで実行するために新しいスレッドが選択されます。

Alertable パラメーターは、スレッドを警告できるタイミングと、その待機状態が結果として中止されるタイミングを決定します。詳細については、「待機と APC」を参照してください。

KeWaitForSingleObject に渡される Object パラメーターがミューテックスである場合は、特別な考慮事項が適用されます。待機しているディスパッチャーオブジェクトがミューテックスの場合、APC 配信は待機中の他のすべてのディスパッチャーオブジェクトの場合と同じです。ただし、 KeWaitForSingleObject が STATUS_SUCCESS で戻り、スレッドが実際にミューテックスを保持した後は、特殊なカーネルモードの APC のみが配信されます。カーネルモードとユーザーモードの両方の他のすべての APC の配信は無効になっています。 APC の配信に関するこの制限は、ミューテックスが解放されるまで保持されます。

Object パラメーターが指すディスパッチャーオブジェクトは、非ページシステムメモリに存在する必要があります。

WaitMode パラメーターが UserMode の場合、待機中にカーネルスタックをスワップアウトできます。そのため、呼び出し元は、UserMode 引数を使用して KeWaitForSingleObject を呼び出すときに、スタックにパラメーターを渡そうとしないでください。スタックにイベントを割り当てる場合は、 WaitMode パラメーターを KernelMode に設定する必要があります。

WaitMode パラメーターが UserMode または Alertable が TRUE の場合は、KeWaitForSingleObject の戻り値をチェックすることが特に重要です。KeWaitForSingleObject は、STATUS_USER_APCまたはSTATUS_ALERTEDの状態で早期に返される可能性があるためです。

ユーザーが中止できるすべての長期待機は UserMode 待機で、 Alertable は FALSE に設定する必要があります。

可能な場合は、ドライバーの複雑さを軽減するために、 Alertable を FALSE に設定し、 WaitMode を KernelMode に設定する必要があります。これに対する主な例外は、待機が長期待機である場合です。

タイムアウトに NULL ポインターが指定された場合、呼び出し元のスレッドは Object が通知されるまで待機状態のままになります。

タイムアウト値が 0 の場合、ミューテックスの取得のように、待機条件のセットをテストし、待機をすぐに満たすことができる場合に副作用の条件付きパフォーマンスをテストできます。

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

ミューテックスは、MINLONG 回だけ再帰的に取得できます。この制限を超えると、ルーチンによってSTATUS_MUTANT_LIMIT_EXCEEDED例外が発生します。

KeWaitForSingleObject の呼び出し元は、IRQL <= DISPATCH_LEVELで実行されている必要があります。ただし、 Timeout = NULL または Timeout != 0 の場合、呼び出し元は IRQL <= APC_LEVELおよび非arbitrary スレッドコンテキストで実行されている必要があります。 Timeout != NULL および Timeout = 0 の場合、呼び出し元は IRQL <= DISPATCH_LEVELで実行されている必要があります。

KeWaitForMutexObject は、代わりに使用できる KeWaitForSingleObject に変換するマクロです。

パフォーマンスを向上させるには、高速ミューテックスまたは保護されたミューテックスを使用します。詳細については、「ミューテックスオブジェクトの代替手段」を参照してください。

ミューテックスオブジェクトの詳細については、「ミューテックスオブジェクト」を参照してください。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	「解説」を参照してください。
DDI コンプライアンス規則	CompleteRequestStatusCheck(wdm)、 HwStorPortProhibitedDDIs(storport)、 IoAllocateIrpSignalEventInCompletionTimeout(wdm)、 IoBuildDeviceControlWait(wdm)、 IoBuildDeviceControlWaitTimeout(wdm)、 IoBuildFsdIrpSignalEventInCompletionTimeout(wdm)、 IoBuildSynchronousFsdRequestWait(wdm)、 IoBuildSynchronousFsdRequestWaitTimeout(wdm)、 IrpProcessingComplete(wdm)、 IrqlKeWaitForMutexObject(wdm)、 LowerDriverReturn(wdm)、 MarkIrpPending2(wdm)、 PendedCompletedRequest(wdm)、 PendedCompletedRequest2(wdm)、 PendedCompletedRequest3(wdm)、 PendedCompletedRequestEx(wdm)、 RemoveLockForwardDeviceControl(wdm)、 RemoveLockForwardDeviceControlInternal(wdm)、 RemoveLockForwardRead(wdm)、 RemoveLockForwardWrite(wdm)、、 SpNoWait(storport)、 StartDeviceWait(wdm)、 StartDeviceWait2(wdm)、 StartDeviceWait3(wdm)、 StartDeviceWait4(wdm)