WaitForMultipleObjectsEx 関数 (synchapi.h)

  • [アーティクル]

指定されたオブジェクトの 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

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

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

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

[in] bWaitAll

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

[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、Windows 8.1、Windows Server 2012 R2、Windows 10、Windows Server 2016: dwMilliseconds 値には低電力状態で経過した時間は含まれません。 たとえば、コンピューターがスリープ状態の間、タイムアウトのカウント ダウンは継続されません。

[in] bAlertable

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

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

戻り値

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

リターン コード/値 Description
にWAIT_OBJECT_0 (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
 待機は、スレッドにキューに入れた 1 つ以上のユーザー モード 非同期プロシージャ呼び出し (APC) によって終了しました。
WAIT_TIMEOUT
0x00000102L
 タイムアウト間隔が経過し、 bWaitAll パラメーターで指定された条件が満たされず、完了ルーチンがキューに登録されていません。
WAIT_FAILED
(DWORD)0xFFFFFFFF
 関数が失敗しました。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

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

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

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

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

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

  • MAXIMUM_WAIT_OBJECTSハンドルを待機するスレッド を 作成し、そのスレッドと他のハンドルで待機します。 ハンドルを MAXIMUM_WAIT_OBJECTSのグループに分割するには、この手法を使用します。
  • RegisterWaitForSingleObject または SetThreadpoolWait を呼び出して、各ハンドルを待機します。 スレッド プールはハンドルで効率的に待機し、オブジェクトがシグナル通知されるか、タイムアウト間隔の有効期限が切れた後にワーカー スレッドを割り当てます。
WaitForMultipleObjectsEx 関数は、lpHandles 配列内の次のいずれかのオブジェクト型のハンドルを指定できます。
  • 変更通知
  • コンソール入力
  • イベント
  • メモリ リソース通知
  • Mutex
  • Process
  • Semaphore
  • スレッド
  • 待機可能タイマー
直接または間接的にウィンドウを作成する待機関数とコードを呼び出す場合は注意が必要です。 スレッドがウィンドウを作成する場合は、メッセージを処理する必要があります。 メッセージ ブロードキャストは、システム内のすべてのウィンドウに送信されます。 タイムアウト間隔のない待機関数を使用するスレッドによって、システムがデッドロックになる可能性があります。 ウィンドウを間接的に作成するコードの例として、DDE と CoInitialize 関数の 2 つがあります。 したがって、ウィンドウを作成するスレッドがある場合は、 WaitForMultipleObjectsEx ではなく MsgWaitForMultipleObjects または MsgWaitForMultipleObjectsExを使用します。

要件

要件 値
サポートされている最小のクライアント Windows XP [デスクトップ アプリ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー synchapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 の Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

同期関数

待機関数