ZwWaitForSingleObject 関数 (ntifs.h)

[アーティクル]
12/21/2024

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 を配信するには、スレッドが警告可能である必要があります。カーネルモードの APCs では、これは当てになりません。カーネルモード APC は、スレッドがアラートを受け取らない場合でも配信および実行できます。 APC の実行が完了すると、スレッドの待機が再開されます。カーネルモード APC の配信によって、スレッドにアラートが送信されたり、待機が中止されたりすることはありません。

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

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

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

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

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

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
ターゲットプラットフォームの	万国
ヘッダー	ntifs.h (Ntifs.h、FltKernel.h を含む)
ライブラリ	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則をする	HwStorPortProhibitedDDIs(storport), SpNoWait(storport)

次の方法で共有

ZwWaitForSingleObject 関数 (ntifs.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース