ZwWaitForSingleObject 関数 (ntifs.h)

[アーティクル]
07/11/2023

ZwWaitForSingleObject ルーチンは、指定されたオブジェクトが Signaled の状態になるまで待機します。省略可能なタイムアウトを指定することもできます。

構文

NTSYSAPI NTSTATUS ZwWaitForSingleObject(
  [in]           HANDLE         Handle,
  [in]           BOOLEAN        Alertable,
  [in, optional] PLARGE_INTEGER Timeout
);

パラメーター

[in] Handle

オブジェクトへのハンドル。

[in] Alertable

待機が警告可能かどうかを示すブール値。

[in, optional] Timeout

待機が完了する絶対時間または相対時間を指定するタイムアウト値への省略可能なポインター。負の値は、現在の時刻を基準とした間隔を指定します。この値は、100 ナノ秒の単位で表す必要があります。絶対有効期限は、システム時刻の変更を追跡します。相対的な有効期限は、システム時刻の変更の影響を受けません。

戻り値

ZwWaitForSingleObject は、次のいずれかの状態コードを返すことができます。

リターンコード	説明
STATUS_ACCESS_DENIED	呼び出し元には、 Handle パラメーターで指定されたイベントに対する必要な特権がありませんでした。
STATUS_ALERTED	現在のスレッドにアラートを配信するために待機が中止されました。
STATUS_INVALID_HANDLE	指定された Handle パラメーターが無効です。
STATUS_SUCCESS	指定したオブジェクトが待機を満たしました。
STATUS_TIMEOUT	オブジェクトがシグナル状態に設定される前にタイムアウトが発生しました。この値は、指定された待機条件のセットをすぐに満たすことができないときに、Timeout パラメーターが 0 に設定されている場合に返すことができます。
STATUS_USER_APC	ユーザー APC を現在のスレッドに配信するための待機が中止されました。

NT_SUCCESS マクロは、STATUS_ALERTED、STATUS_SUCCESS、STATUS_TIMEOUT、STATUS_USER_APC状態の値を "success" 値として認識します。

注釈

ZwWaitForSingleObject は 、指定されたオブジェクトが Signaled の状態になるまで待機します。省略可能なタイムアウトを指定することもできます。 ZwWaitForSingleObject は、指定されたオブジェクトの現在の状態を調べて、待機をすぐに満たすことができるかどうかを判断します。その場合、アクションが実行されます。それ以外の場合、現在のスレッドは待機状態になり、現在のプロセッサで実行するために新しいスレッドが選択されます。

Timeout パラメーターが指定されていない場合、オブジェクトが Signaled の状態になるまで待機は満たされません。 Timeout パラメーターを指定し、タイムアウトが切れたときにオブジェクトが Signaled の状態を取得していない場合、待機は自動的に満たされます。明示的な タイムアウト 値 0 を指定した場合、待機をすぐに満たすことができない場合、待機は発生しません。 タイムアウト値が 0 の場合、ミューテックスの取得と同様に、待機条件のセットをテストし、待機をすぐに満たすことができる場合に副作用の条件付きパフォーマンスをテストできます。待機は、アラート可能として指定することもできます。

Alertable パラメーターは、スレッドを警告できるかどうかを指定し、その結果、待機状態を中止します。このパラメーターの値が FALSE の場合、スレッドを警告することはできません。この規則の唯一の例外は、終了スレッドの例外です。特定の状況では、終了するスレッドが巻き込まれている間にアラートを受け取ることができます。たとえば、ユーザーが Ctrl + C キーを押して終了すると、スレッドは自動的に警告可能になります。

Alertableの値が TRUE で、次のいずれかの条件が存在する場合、スレッドは警告されます。

アラートの配信元が、スレッドの警告に使用される、文書化されていない内部カーネルモードルーチンである場合。
アラートの配信元は、ユーザーモードの APC です。

これら 2 つのケースの最初のケースでは、スレッドの待機が完了状態の STATUS_ALERTED で満たされます。 2 番目のケースでは、完了状態が STATUS_USER_APC で満たされます。

ユーザーモード APC を配信するには、スレッドがアラート可能である必要があります。カーネルモードの APC では、これは当てはまれません。スレッドが警告されない場合でも、カーネルモードの APC を配信して実行できます。 APC の実行が完了すると、スレッドの待機が再開されます。スレッドは、カーネルモード APC の配信によって警告されたり、待機が中止されたりすることはありません。

待機中のスレッドへのカーネルモードの APC の配信は、スレッドを警告できるかどうかによって異なります。カーネルモード APC が特殊なカーネルモード APC の場合、IRQL がAPC_LEVEL未満の場合、APC が配信されます。カーネルモード APC が通常のカーネルモード APC の場合、次の 3 つの条件が保持されている場合、APC が配信されます。(1) IRQL がAPC_LEVEL未満であること、(2) カーネル APC が進行中ではなく、(3) スレッドがクリティカルセクションにない場合。

ZwWaitForSingleObject に渡されるハンドルがミューテックスを参照している場合、APC 配信は待機中の他のすべてのディスパッチャーオブジェクトの場合と同じです。ただし、 ZwWaitForSingleObject が STATUS_SUCCESS でを返し、スレッドが実際にミューテックスを保持すると、特別なカーネルモードの APC のみが配信されます。カーネルモードとユーザーモードの両方の他のすべての APC の配信は無効になっています。 APC の配信に関するこの制限は、ミューテックスが解放されるまで保持されます。

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

Alertable パラメーターが FALSE に設定されている場合、すべての長期待機をユーザーが中止できます。

詳細については、「待機中のスレッドはアラートと APCs を受信しますか?」を参照してください。

ZwWaitForSingleObject の呼び出し元は、DISPATCH_LEVEL以下の IRQL で実行されている必要があります。通常、呼び出し元は IRQL PASSIVE_LEVELおよび非arbitrary スレッドコンテキストで実行されている必要があります。 IRQL DISPATCH_LEVELで実行中の呼び出しは、呼び出し元が Timeout パラメーターを 0 に指定した場合にのみ有効です。つまり、ドライバーは、IRQL がDISPATCH_LEVELと等しい 0 以外の間隔を待つ必要があります。

タイムアウト間隔はシステムクロックに対して測定され、タイムアウト測定の精度はシステムクロックの粒度によって制限されます。詳細については、「タイマーの精度」を参照してください。

ZwWaitForSingleObject 関数の呼び出しがユーザーモードで行われる場合は、"ZwWaitForSingleObject" ではなく"NtWaitForSingleObject" という名前を使用する必要があります。

カーネルモードドライバーからの呼び出しの場合、Windows ネイティブシステムサービスルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。 ルーチンの NtXxx バージョンと ZwXxx バージョンの間の関係の詳細については、「ネイティブシステムサービスルーチンの Nt バージョンと Zw バージョンの使用」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP
対象プラットフォーム	ユニバーサル
Header	ntifs.h (Ntifs.h、FltKernel.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), SpNoWait(storport)