WaitForMultipleObjectsEx 関数 (synchapi.h)

[アーティクル]
11/08/2024

指定したオブジェクトの 1 つ以上がシグナル状態になるまで待機するか、I/O 完了ルーチンまたは非同期プロシージャ呼び出し (APC) がスレッドにキューに登録されるか、タイムアウト間隔が経過するまで待機します。

構文

DWORD WaitForMultipleObjectsEx(
  [in] DWORD        nCount,
  [in] const HANDLE *lpHandles,
  [in] BOOL         bWaitAll,
  [in] DWORD        dwMilliseconds,
  [in] BOOL         bAlertable
);

パラメーター

[in] nCount

lpHandlesが指す配列内で待機するオブジェクトハンドル数。オブジェクトハンドルの最大数は MAXIMUM_WAIT_OBJECTS。このパラメーターを 0 にすることはできません。

[in] lpHandles

オブジェクトハンドルの配列。ハンドルを指定できるオブジェクトの種類の一覧については、次の「解説」セクションを参照してください。配列には、さまざまな型のオブジェクトのハンドルを含めることができます。同じハンドルの複数のコピーが含まれていない場合があります。

待機がまだ保留中の間にこれらのハンドルのいずれかが閉じられた場合、関数の動作は未定義です。

ハンドルには、SYNCHRONIZE アクセス権が必要です。詳細については、「Standard Access Rights」を参照してください。

[in] bWaitAll

このパラメーターが TRUE場合、この関数は、lpHandles 配列内のすべてのオブジェクトの状態が signaled に設定されたときに返されます。 FALSE場合、いずれかのオブジェクトの状態がシグナル通知に設定されたときに関数が返されます。後者の場合、戻り値は、関数が戻る原因となった状態のオブジェクトを示します。

[in] dwMilliseconds

タイムアウト間隔 (ミリ秒単位)。 0 以外の値を指定した場合、関数は、指定されたオブジェクトが通知されるまで待機するか、I/O 完了ルーチンまたは APC がキューに登録されるか、または間隔が経過するまで待機します。 dwMilliseconds が 0 の場合、条件が満たされていない場合、関数は待機状態になりません。常にすぐに返されます。 dwMilliseconds が INFINITE場合、関数は、指定されたオブジェクトが通知されるか、I/O 完了ルーチンまたは APC がキューに登録されている場合にのみ返されます。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008、および Windows Server 2008 R2:dwMilliseconds 値には、低電力状態で費やされた時間が含まれます。たとえば、コンピューターがスリープ状態の間、タイムアウトはカウントダウンし続けます。

Windows 8 以降、Windows Server 2012 以降:dwMilliseconds 値には、低電力状態で費やされた時間は含まれません。たとえば、コンピューターがスリープ状態の間にタイムアウトがカウントダウンし続けないようにします。

[in] bAlertable

このパラメーターが TRUE 、スレッドが待機状態の場合、システムが I/O 完了ルーチンまたは APC をキューに入れ、スレッドがルーチンまたは関数を実行するときに関数が返されます。それ以外の場合、関数は戻らず、完了ルーチンまたは APC 関数は実行されません。

完了ルーチンは、ReadFileEx または指定された WriteFileEx 関数が完了したときにキューに入れられます。待機関数が戻り、bAlertable TRUE がされ、呼び出し元のスレッドが読み取りまたは書き込み操作を開始したスレッドである場合にのみ、完了ルーチンが呼び出されます。 QueueUserAPC呼び出すと、APC がキューに登録されます。

戻り値

関数が成功した場合、戻り値は関数が戻る原因となったイベントを示します。次のいずれかの値を指定できます。 (WAIT_OBJECT_0 は 0 として定義され、WAIT_ABANDONED_0 は 0x00000080L として定義されることに注意してください)。

戻りコード/値	形容
WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount– 1)	bWaitAll が TRUE場合、この範囲内の戻り値は、指定されたすべてのオブジェクトの状態が通知されることを示します。 bWaitAll が FALSE場合、戻り値から WAIT_OBJECT_0 を引いた値は、待機を満たすオブジェクトの配列インデックス lpHandles を示します。呼び出し中に複数のオブジェクトがシグナル通知された場合、これはシグナルオブジェクトの配列インデックスであり、すべてのシグナルオブジェクトのインデックス値が最小になります。
WAIT_ABANDONED_0 (WAIT_ABANDONED_0 + nCount– 1)	bWaitAll が TRUE場合、この範囲の戻り値は、指定されたすべてのオブジェクトの状態が通知され、少なくとも 1 つのオブジェクトが破棄されたミューテックスオブジェクトであることを示します。 bWaitAll が FALSE場合、戻り値から WAIT_ABANDONED_0 を引いた値は、待機を満たす破棄されたミューテックスオブジェクトの配列インデックス lpHandles を示します。ミューテックスオブジェクトの所有権は呼び出し元のスレッドに付与され、ミューテックスは非署名に設定されます。ミューテックスが永続的な状態情報を保護していた場合は、整合性を確認する必要があります。
WAIT_IO_COMPLETION 0x000000C0L	スレッドにキューに入 (APC) の非同期プロシージャ呼び出し、1 つ以上のユーザーモードによって待機が終了しました。
WAIT_TIMEOUT 0x00000102L	タイムアウト間隔が経過しました。bWaitAll パラメーターで指定された条件が満たされておらず、完了ルーチンはキューに登録されていません。
WAIT_FAILED (DWORD)0xFFFFFFFF	関数が失敗しました。拡張エラー情報を取得するには、GetLastError呼び出します。

備考

WaitForMultipleObjectsEx 関数は、待機条件が満たされているかどうかを判断します。条件が満たされていない場合、呼び出し元のスレッドは、待機条件の条件が満たされるかタイムアウト間隔が経過するまで待機状態に入ります。

bWaitAll が TRUE場合、関数の待機操作は、すべてのオブジェクトの状態がシグナル通知に設定されている場合にのみ完了します。この関数は、すべてのオブジェクトの状態がシグナル通知に設定されるまで、指定されたオブジェクトの状態を変更しません。たとえば、ミューテックスを通知することはできますが、他のオブジェクトの状態もシグナル通知に設定されるまで、スレッドは所有権を取得しません。それまでの間、他のスレッドがミューテックスの所有権を取得し、その状態を非署名に設定する場合があります。

bWaitAll が FALSE場合、この関数は、オブジェクトの 1 つが通知されるまで、インデックス 0 で始まる順序で配列内のハンドルをチェックします。複数のオブジェクトがシグナル通知された場合、関数はオブジェクトがシグナル通知された配列内の最初のハンドルのインデックスを返します。

この関数は、一部の種類の同期オブジェクトの状態を変更します。変更は、シグナル状態によって関数が戻される原因となったオブジェクトに対してのみ行われます。たとえば、セマフォオブジェクトの数は 1 ずつ減少します。詳細については、個々の同期オブジェクトのドキュメントを参照してください。

MAXIMUM_WAIT_OBJECTS を超えるハンドルを待機するには、次のいずれかの方法を使用します。

MAXIMUM_WAIT_OBJECTS ハンドルを待機するスレッドを作成し、そのスレッドと他のハンドルを待機します。この手法を使用して、ハンドルを MAXIMUM_WAIT_OBJECTSのグループに分割します。
RegisterWaitForSingleObject 呼び出すか、SetThreadpoolWait をして各ハンドルを待機します。スレッドプールはハンドルで効率的に待機し、オブジェクトが通知されるかタイムアウト間隔が切れた後にワーカースレッドを割り当てます。

WaitForMultipleObjectsEx 関数は、lpHandles 配列内の次のいずれかのオブジェクト型のハンドルを指定できます。

変更通知
コンソール入力
出来事
メモリリソース通知
ミューテックス
過程
セマフォ
糸
待機可能タイマー

直接または間接的にウィンドウを作成する待機関数とコードを呼び出す場合は注意が必要です。スレッドがウィンドウを作成する場合は、メッセージを処理する必要があります。メッセージブロードキャストは、システム内のすべてのウィンドウに送信されます。タイムアウト間隔のない待機関数を使用するスレッドによって、システムがデッドロックになる可能性があります。ウィンドウを間接的に作成するコードの 2 つの例は、DDE と CoInitialize 関数です。したがって、ウィンドウを作成するスレッドがある場合は、WaitForMultipleObjectsEx ではなく、MsgWaitForMultipleObjectsEx または MsgWaitForMultipleObjectsEx使用します。

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリ \|UWP アプリ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリ \|UWP アプリ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	synchapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 の Windows.h を含む)
ライブラリ	Kernel32.lib
DLL	Kernel32.dll

次の方法で共有

WaitForMultipleObjectsEx 関数 (synchapi.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース