共用方式為

WaitForMultipleObjectsEx 函式 (synchapi.h)

  • 發行項

等候一或所有指定的對象處於訊號狀態、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。 此參數不可為零。

[in] lpHandles

物件句柄的陣列。 如需可以指定句柄的物件類型清單，請參閱下列一節。 數位可以包含不同類型物件的句柄。 它可能不會包含相同句柄的多個複本。

如果等候仍在擱置時關閉其中一個句柄，則函式的行為是未定義的。

句柄必須具有 SYNCHRONIZE 訪問許可權。 如需詳細資訊，請參閱 標準訪問許可權。

[in] bWaitAll

勾選此參數為 TRUE，當 lpHandles 陣列中的所有物件狀態設定為已發出訊號時，函式會傳回 。 如果為 FALSE，當任一物件的狀態設定為已發出訊號時，函式會傳回 。 在後者的情況下，傳回值會指出其狀態導致函式傳回的物件。

[in] dwMilliseconds

超時時間間隔，以毫秒為單位。 如果指定了非零值，函式會等到指定的物件收到訊號、已排入佇列的 I/O 完成例程或 APC，或經過間隔為止。 如果 dwMilliseconds 為零，則如果不符合準則，函式就不會進入等候狀態;它一律會立即傳回。 如果 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 且呼叫線程是起始讀取或寫入作業的線程時，等候函式才會傳回並呼叫完成例程。 當您呼叫 QueueUserAPC 時，APC 會排入佇列。

傳回值

如果函式成功，傳回值會指出導致函式傳回的事件。 它可以是下列值之一。 (請注意，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，這個範圍中的傳回值表示所有指定物件的狀態都會發出訊號，而且至少有一個物件是已放棄的 Mutex 物件。

如果 bWaitAll 為 FALSE，則傳回值減 去 WAIT_ABANDONED_0 表示已放棄 mutex 物件的 lpHandles 陣列索引，該物件滿足等候。 mutex 對象的擁有權會授與呼叫線程，且 mutex 設定為非ignaled。

如果 Mutex 保護持續性狀態資訊，您應該檢查其是否一致性。
WAIT_IO_COMPLETION
0x000000C0L
 等候已由一或多個使用者模式 異步過程調用 結束， (APC) 佇列至線程。
WAIT_TIMEOUT
0x00000102L
 經過逾時間隔、 不符合 bWaitAll 參數所指定的條件，而且不會排入佇列中。
WAIT_FAILED
(DWORD) 0xFFFFFFFF
 函式失敗。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

WaitForMultipleObjectsEx 函式會判斷是否已符合等候準則。 如果不符合準則，則呼叫線程會進入等候狀態，直到符合等候準則的條件或逾時間隔經過為止。

當 bWaitAll 為 TRUE 時，只有在所有物件的狀態都已設定為已發出訊號時，函式的等候作業才會完成。 函式不會修改指定物件的狀態，直到所有物件的狀態都設定為已發出訊號為止。 例如，可以發出 mutex 的訊號，但是線程在其他物件的狀態也設定為已發出訊號之前，不會取得擁有權。 同時，有些其他線程可能會取得 Mutex 的擁有權，藉此將其狀態設定為非ignaled。

當 bWaitAll 為 FALSE 時，此函式會檢查數位中的句柄，從索引 0 開始，直到收到其中一個物件的訊號為止。 如果有多個物件收到訊號，函式會傳回陣列中對象已發出訊號的第一個句柄索引。

函式會修改某些同步處理物件類型的狀態。 修改只會針對發出訊號狀態導致函式傳回的物件或對象進行。 例如，號誌物件的計數會減少一。 如需詳細資訊，請參閱個別同步處理對象的檔。

若要等候多個 MAXIMUM_WAIT_OBJECTS 句柄，請使用下列其中一種方法：

  • 建立線程以等候 MAXIMUM_WAIT_OBJECTS 句柄，然後等候該線程加上其他句柄。 使用這項技術將句柄分成 MAXIMUM_WAIT_OBJECTS群組。
  • 呼叫 RegisterWaitForSingleObject 或 SetThreadpoolWait 以等候每個句柄。 線程集區會在句柄上有效率地等候，並在發出訊號或逾時間隔到期之後指派背景工作線程。
WaitForMultipleObjectsEx 函式可以指定 lpHandles 陣列中下列任何物件類型的句柄：
  • 變更通知
  • 主控台輸入
  • 事件
  • 記憶體資源通知
  • Mutex
  • 流程
  • Semaphore
  • 執行緒
  • 可等候定時器
呼叫直接或間接建立視窗的等候函式和程式代碼時，請小心。 如果線程建立任何視窗，它就必須處理訊息。 訊息廣播會傳送至系統中的所有視窗。 使用沒有超時時間間隔之等候函式的線程可能會導致系統死結。 間接建立視窗的程式代碼範例包括 DDE 和 CoInitialize 函式。 因此，如果您有建立窗口的線程，請使用 MsgWaitForMultipleObjects 或 MsgWaitForMultipleObjectsEx，而不是 WaitForMultipleObjectsEx。

規格需求

需求 值
最低支援的用戶端 Windows XP [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 synchapi.h (包含 Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

同步處理函式

Wait 函式