FsRtlCancellableWaitForMultipleObjects 関数 (ntifs.h)

FsRtlCancellableWaitForMultipleObjects ルーチンは、1 つ以上のディスパッチャー オブジェクトに対してキャンセル可能な待機操作 (終了可能な待機) を実行します。

構文

NTSTATUS FsRtlCancellableWaitForMultipleObjects(
  [in]           ULONG          Count,
  [in]           PVOID []       ObjectArray,
  [in]           WAIT_TYPE      WaitType,
  [in, optional] PLARGE_INTEGER Timeout,
  [in, optional] PKWAIT_BLOCK   WaitBlockArray,
  [in, optional] PIRP           Irp
);

パラメーター

[in] Count

待機するオブジェクトの数。

[in] ObjectArray

呼び出し元がストレージを提供するディスパッチャー オブジェクト (イベント、ミューテックス、セマフォ、スレッド、タイマー) へのポインターの配列へのポインター。

[in] WaitType

WaitAllします。これは、待機が満たされる前に、指定されたすべてのオブジェクトがシグナル状態を取得する必要があることを示します。または waitAnyを します。これは、待機が満たされる前に、いずれかのオブジェクトがシグナル状態を取得する必要があることを示します。

[in, optional] Timeout

省略可能なタイムアウト値へのポインター。 このパラメーターは、待機が完了する絶対時間または相対時間を 100 ナノ秒単位で指定します。

Timeout がゼロ値 (つまり、 *Timeout == 0) を指している場合、ルーチンは待機せずに戻ります。 呼び出し元が NULL ポインター (つまり、タイムアウト == NULL) を指定した場合、ルーチンは、ディスパッチャー オブジェクトの一部またはすべてがシグナル状態に設定されるまで無期限に待機します。

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

タイムアウト が指定されている場合、指定した間隔の有効期限が切れたときに指定された待機条件が満たされない場合、待機は自動的に満たされます。

タイムアウト値 0 (つまり、*Timeout == 0) を使用すると、一連の待機条件をテストし、ミューテックスの取得のように、待機をすぐに満たすことができる場合は、条件付きで追加のアクションを実行できます。

[in, optional] WaitBlockArray

Count= THREAD_WAIT_OBJECTSの場合、WaitBlockArray NULL を指定できます。 それ以外の場合、このパラメーターは、sizeof(KWAIT_BLOCK * Count) バイトのメモリ バッファーを指す必要があります。 このルーチンは、待機操作の実行中にレコードを保持するためにこのバッファーを使用します。

[in, optional] Irp

ユーザーによって発行され、ユーザーが取り消すことができる I/O 操作に対応する元の IRP へのポインター。 呼び出し元は、IRP がこのルーチンの期間中有効であり、IRP がキャンセル ルーチンセットを持つ必要がないことを確認する必要があります (たとえば、IoSetCancelRoutine が IRP で呼び出されていない必要があります)。 IRP は呼び出し元が保持する必要があります。下位レベルのドライバーに渡すことはできません。

戻り値

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

戻り値は、待機の状態のみを示します。 該当する場合は、元のユーザー モード IRP を処理するプロセスで生成された別の IRP から、I/O 要求の実際の状態を直接取得する必要があります。

NT_SUCCESS マクロは、STATUS_CANCELLEDおよびSTATUS_THREAD_IS_TERMINATING状態値に対して FALSE ("failure") を返し、その他のすべての状態値に対して TRUE ("success") を返します。

備考

FsRtlCancellableWaitForMultipleObjects ルーチンは、ディスパッチャー オブジェクトに対してキャンセル可能な待機操作を実行します。 スレッドがユーザーまたはアプリケーションによって終了された場合、または CancelSynchronousIo がスレッドに関連付けられているスレッド IRP (同期 IRP) にキャンセル要求を投稿した場合、待機は取り消されます。

FsRtlCancellableWaitForMultipleObjects ルーチンは、Windows Vista 以降 I/O 完了/取り消しガイドラインをサポートするように設計されています。 これらのガイドラインの目的は、ユーザー (またはアプリケーション) がアプリケーションをすばやく終了できるようにすることです。 その結果、アプリケーションでは、I/O を実行しているスレッドと現在の I/O 操作を迅速に終了できる必要があります。 このルーチンは、ユーザー スレッドが I/O 完了、ディスパッチャー オブジェクト、または同期変数のカーネルでブロック (つまり、待機) する方法を提供します。これにより、待機を簡単に取り消すことができます。 このルーチンでは、スレッドがユーザーまたはアプリケーションによって終了された場合に、スレッドの待機を終了することもできます。

たとえば、リダイレクターは、ユーザー モード IRP を処理し、セカンダリ IRP が完了するまで同期的に待機するために、1 つ以上のセカンダリ IRP を作成する必要がある場合があります。 これを行う 1 つの方法は、セカンダリ IRP の完了ルーチンによって通知されるイベントを設定し、イベントが通知されるまで待機することです。 次に、キャンセル可能な待機操作を実行するために、fsRtlCancellableWaitForMultipleObjects 、セカンダリ IRP に関連付けられたイベントと元のユーザー モード IRP を渡して呼び出されます。 保留中の終了イベントが発生した場合、または元のユーザー モード IRP が取り消された場合、スレッドが通知されるイベントの待機は取り消されます。

待機を終了しても、呼び出し元によって発行された I/O 操作は自動的に取り消されません。呼び出し元が個別に処理する必要があります。

各スレッド オブジェクトには、複数のオブジェクトを同時に待機するために使用できる待機ブロックの組み込み配列があります。 可能な限り、待機ブロックの組み込み配列を wait-multiple 操作で使用する必要があります。これは、追加の待機ブロック ストレージを割り当て、後で割り当てを解除する必要がないためです。 ただし、同時に待機する必要があるオブジェクトの数が組み込みの待機ブロックの数を超える場合は、WaitBlockArray パラメーターを使用して、待機操作で使用する待機ブロックの代替セットを指定します。 ドライバーは、WaitBlockArrayに十分な大きさのメモリ バッファーを割り当てるだけで済みます。 バッファーを初期化する必要はありません。ドライバーは、それを不透明な構造体として扱うことができます。 ルーチンから制御が戻ったら、バッファーを解放できます。

Count が MAXIMUM_WAIT_OBJECTS より大きい場合、または WaitBlockArray が NULL で Count が THREAD_WAIT_OBJECTS より大きい場合、システムはバグ チェック 0xC 発行します:MAXIMUM_WAIT_OBJECTS_EXCEEDED。

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

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

省略可能な Irp パラメーターが有効な IRP を指している場合は、FsRtlCancellableWaitForMultipleObjects を IRQL PASSIVE_LEVELで呼び出す必要があります。 Irp パラメーターを使用しない場合は、IRQL でAPC_LEVEL以下でルーチンを呼び出すことができます。 通常のカーネル APCs は、必要に応じて、KeEnterCriticalRegion または FsRtlEnterFileSystem ルーチンを呼び出すことによって、呼び出し元によって無効にすることができます。 ただし、特殊なカーネル API は無効にしないでください。

FsRtlCancellableWaitForMultipleObjects は、IRQL がAPC_LEVEL以上で、Irp パラメーターが有効な IRP を指している場合、デバッグ ビルドでアサートされます。

必要条件

関連項目

ExInitializeFastMutex の

FsRtlCancellableWaitForSingleObject

KeInitializeEvent

KeInitializeMutex

KeInitializeSemaphore

KeInitializeTimer の

KeWaitForMultipleObjects

KeWaitForSingleObject

KeWaitForMutexObject の