WaitForMultipleObjects

指定されたカーネルオブジェクトのうちの1つまたはそれらのすべてがシグナル状態になるか、指定された時間が経過するまで待機します。

アラート可能待機状態に入るには、WaitForMultipleObjectsEx関数を使用します。

DWORD WaitForMultipleObjects(
    DWORD  nCount,
    const HANDLE *lpHandles,
    BOOL   bWaitAll,
    DWORD  dwMilliseconds
);

KERNEL32.DLL

引数

nCount

lpHandlesパラメータが指し示す配列のカーネルオブジェクトのハンドルの数を指定します。指定できるオブジェクトの最大数は64 (MAXIMUM_WAIT_OBJECTS) 個です。

lpHandles

カーネルオブジェクトのハンドルを格納した配列変数のアドレスを指定します。配列には異なるタイプのオブジェクトのハンドルを含めることができます。同じオブジェクトハンドルを複数個含めることはできません

待機が未解決の状態でこれらのハンドルの1つがクローズされた場合の関数の動作は定義されていません。

オブジェクトのハンドルはSYNCHRONIZEアクセス権を持っていなければなりません。

bWaitAll

リスト内のすべてのオブジェクトを待つか、どれか1つのみを待つかを指定します。1 (TRUE) を指定すると、lpHandlesが指す配列に含まれているすべてのオブジェクトがシグナル状態になると関数が制御を返します。0 (FALSE) を指定すると、どれか1つがシグナル状態になるのを待ちます。

dwMilliseconds

待ち時間をミリ秒単位で指定します。0を指定すると、オブジェクトがシグナル状態かどうかを調べてすぐに制御を返します。0xFFFFFFFF (INFINITE) を指定すると、オブジェクトがシグナル状態になるまで無限に待ち続けます。

戻り値

以下の値のいずれかを返します。

0x00000000 (WAIT_OBJECT_0) から (WAIT_OBJECT_0 + nCount - 1) まで

bWaitAllにTRUEをした場合、戻り値は指定されたすべてのオブジェクトがシグナル状態になったことを示します。

bWaitAllにFALSEをした場合、(戻り値 - WAIT_OBJECT_0) の値は、lpHandlesが指す配列における、待機条件を満たしたオブジェクトのインデックスを示します。呼び出し中に複数のオブジェクトがシグナル状態になった場合は、すべてのシグナル状態にされたオブジェクトの中でもっとも小さいインデックスを持つオブジェクトの配列インデックスになります。

0x00000080 (WAIT_ABANDONED) から (WAIT_ABANDONED + nCount - 1) まで

bWaitAllにTRUEをした場合、戻り値は指定されたすべてのオブジェクトがシグナル状態になったことを示し、少なくとも1つのオブジェクトが放棄されたミューテックスオブジェクトであることを示します。

bWaitAllにFALSEをした場合、(戻り値 - WAIT_ABANDONED) の値は、lpHandlesが指す配列における、待機条件を満たした放棄されたミューテックスオブジェクトのインデックスを示します。ミューテックスオブジェクトの所有権は呼び出しスレッドに与えられ、ミューテックスは非シグナル状態に設定されます。

ミューテックスが永続的な状態情報を保護している場合には、整合性を保つためにこの戻り値を確認すべきです。

0x00000102 (WAIT_TIMEOUT)

タイムアウト時間が経過したことを示します。

0xFFFFFFFF (WAIT_FAILED)

エラーが発生したことを示します。拡張エラー情報を取得するには、GetLastError関数を使います。

解説

WaitForMultipleObjects関数は、指定されたオブジェクトの現在の状態をチェックします。オブジェクトが非シグナル状態の場合は、オブジェクトがシグナル状態になるかタイムアウト時間が経過するまで、呼び出しスレッドは待機状態となります。

bWaitAllパラメータが1 (TRUE) の場合、すべてのオブジェクトの状態が支部なる状態にセットされた場合にのみ関数の待機操作が完了します。関数は、すべてのオブジェクトがシグナル状態に設定されるまで、指定されたオブジェクトの状態を変更しません。例えば、ミューテックスはシグナル状態がシグナル化されても、それ以外のオブジェクトもまたシグナル状態に設定されない限り、スレッドは所有権を取得しません。その間に、他のあるスレッドがそのミューテックスの所有権を取得し、その結果としてそのミューテックスの状態を非シグナル状態に設定する可能性があります。

bWaitAllパラメータが0 (FALSE) の場合、指定されたオブジェクトの1つがシグナル化されるまで、インデックス0から順に配列の中のハンドルをチェックします。複数のオブジェクトがシグナル化された場合は、関数はそれらのシグナル化されたオブジェクトの配列に含まれる最初のハンドルのインデックスを返します。

この関数はいくつかの型の同期オブジェクトの状態を変更します。状態の変更は、シグナル状態が関数が制御を返す原因となったオブジェクトに対して加えられます。例えば、セマフォオブジェクトのカウントが1だけデクリメントされます。

64 (MAXIMUM_WAIT_OBJECTS) 個より多くのハンドルを待機するには以下の方法を使用します。

64 (MAXIMUM_WAIT_OBJECTS) 個のハンドルを待機するスレッドを作成し、そのスレッドとそれ以外の待機オブジェクトのハンドルを待機します。この方法を使用して、ハンドルを64 (MAXIMUM_WAIT_OBJECTS) 個ずつのグループに分割します。
RegisterWaitForSingleObjectを呼び出してそれぞれのハンドルを待機します。スレッドプール由来の待機スレッドが64 (MAXIMUM_WAIT_OBJECTS) 個の登録オブジェクトを待機し、オブジェクトがシグナル化されるかタイムアウト時間が経過した後に作業スレッドを割り当てます。

この関数のpHandlesパラメータが指す配列には、以下のカーネルオブジェクトのハンドルを指定することができます。

ファイル変更通知
コンソール入力
イベント
メモリリソース通知
ジョブ
ミューテックス
プロセス
セマフォ
スレッド
ウェイタブルタイマ

待機関数およびウィンドウを直接または間接的に作成するコードを呼び出す際には注意が必要です。スレッドがウィンドウを作成する場合、スレッドはメッセージを処理しなければいけません。メッセージブロードキャストはシステムのすべてのウィンドウに送信されます。タイムアウト時間を指定せずに（INFINITEを指定して）待機関数を使用するスレッドが、システムをデッドロック状態に陥らせる可能性があります。間接的にウィンドウを作成するコードの例として、DDEやCoInitialize関数があります。そのため、スレッドがウィンドウを作成する場合は、MsgWaitForMultipleObjectsまたはMsgWaitForMultipleObjectsEx関数を使用します。

対応情報

Windows 95 以降 / Windows NT 3.1 以降