WaitForMultipleObjects 函数 (synchapi.h)

等待一个或多个指定对象处于信号状态或超时间隔过。

若要进入可警报的等待状态,请使用 WaitForMultipleObjectsEx 函数。

语法

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

参数

[in] nCount

lpHandles指向的数组中的对象句柄数。 对象句柄的最大数目为 MAXIMUM_WAIT_OBJECTS。 此参数不能为零。

[in] lpHandles

对象句柄数组。 有关可以指定句柄的对象类型的列表,请参阅以下“备注”部分。 数组可以包含不同类型的对象的句柄。 它可能不包含同一句柄的多个副本。

如果在等待仍在挂起时关闭其中一个句柄,则函数的行为未定义。

句柄必须具有 SYNCHRONIZE 访问权限。 有关详细信息,请参阅 标准访问权限

[in] bWaitAll

如果此参数 TRUE,则当发出 lpHandles 数组中的所有对象的状态时,该函数将返回。 如果 FALSE,则当任一对象的状态设置为信号时,函数将返回。 在后一种情况下,返回值指示其状态导致函数返回的对象。

[in] dwMilliseconds

超时间隔(以毫秒为单位)。 如果指定了非零值,则函数将等待指定对象发出信号或间隔。 如果 dwMilliseconds 为零,则如果未向指定对象发出信号,则函数不会进入等待状态;它始终会立即返回。 如果 dwMillisecondsINFINITE,则函数仅在发出指定对象的信号时返回。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 和 Windows Server 2008 R2:dwMilliseconds 值确实包括用于低功率状态的时间。 例如,当计算机处于睡眠状态时,超时确实会不断倒计时。

Windows 8 及更新版本、Windows Server 2012 及更新版本:dwMilliseconds 值不包括在低功率状态下花费的时间。 例如,当计算机处于睡眠状态时,超时不会不断倒计时。

返回值

如果函数成功,则返回值指示导致函数返回的事件。 它可以是以下值之一。 (请注意,WAIT_OBJECT_0 定义为 0,WAIT_ABANDONED_0 定义为 0x00000080L。

返回代码/值 描述
WAIT_OBJECT_0 到 (WAIT_OBJECT_0 + nCount– 1)
如果 bWaitAllTRUE,则指定范围内的返回值指示所有指定对象的状态已发出信号。

如果 bWaitAllFALSE,则返回值减 WAIT_OBJECT_0 指示满足等待的对象 lpHandles 数组索引。 如果在调用期间发出了多个对象的信号,则这是信号对象的数组索引,其索引值为所有信号对象的最小索引值。

WAIT_ABANDONED_0 到 (WAIT_ABANDONED_0 + nCount– 1)
如果 bWaitAll为 TRUE,则指定范围内的返回值指示所有指定对象的状态已发出信号,并且至少有一个对象是放弃的互斥对象。

如果 bWaitAllFALSE,则返回值减去 WAIT_ABANDONED_0 指示满足等待的已放弃互斥体对象的 lpHandles 数组索引。 mutex 对象的所有权授予调用线程,互斥体设置为非对齐。

如果互斥体保护持久状态信息,则应检查它是否一致性。

WAIT_TIMEOUT
0x00000102L
不满足 bWaitAll 参数指定的超时间隔和条件。
WAIT_FAILED
DWORD)0xFFFFFFFF
函数失败。 若要获取扩展的错误信息,请调用 GetLastError

言论

WaitForMultipleObjects 函数确定是否满足等待条件。 如果条件尚未满足,则调用线程将进入等待状态,直到满足等待条件的条件或超时间隔已过。

bWaitAllTRUE时,函数的等待操作仅当所有对象的状态都设置为信号时才完成。 该函数不会修改指定对象的状态,直到所有对象的状态都设置为信号。 例如,可以发出互斥体信号,但在其他对象的状态也设置为信号之前,线程不会获得所有权。 同时,其他一些线程可能会获取互斥体的所有权,从而将其状态设置为非对齐状态。

bWaitAllFALSE时,此函数会检查数组中的句柄,从索引 0 开始,直到发出其中一个对象的信号。 如果多个对象被发出信号,该函数将返回数组中第一个句柄的索引,该句柄已发出信号。

该函数修改某些类型的同步对象的状态。 仅针对其信号状态导致函数返回的对象或对象进行修改。 例如,信号灯对象的计数减少一个。 有关详细信息,请参阅各个同步对象的文档。

若要等待多个 MAXIMUM_WAIT_OBJECTS 句柄,请使用以下方法之一:

  • 创建一个线程来等待 MAXIMUM_WAIT_OBJECTS 句柄,然后等待该线程和其他句柄。 使用此技术可将句柄分解为 MAXIMUM_WAIT_OBJECTS组。
  • 调用 RegisterWaitForSingleObjectSetThreadpoolWait 等待每个句柄。 线程池在句柄上高效等待,并在发出对象信号或超时间隔过期后分配工作线程。
WaitForMultipleObjects 函数可以指定 lpHandles 数组中以下任何对象类型的句柄:
  • 更改通知
  • 控制台输入
  • 事件
  • 内存资源通知
  • Mutex
  • 过程
  • 信号
  • 线
  • 可等待计时器
调用直接或间接创建窗口的等待函数和代码时,请谨慎使用。 如果线程创建任何窗口,则必须处理消息。 消息广播将发送到系统中的所有窗口。 使用没有超时间隔的等待函数的线程可能会导致系统陷入死锁。 间接创建窗口的两个代码示例是 DDE 和 CoInitialize 函数。 因此,如果你有一个创建窗口的线程,请使用 MsgWaitForMultipleObjectsMsgWaitForMultipleObjectsEx,而不是 WaitForMultipleObjects

例子

有关示例,请参阅 等待多个对象

要求

要求 价值
最低支持的客户端 Windows XP [桌面应用 |UWP 应用]
支持的最低服务器 Windows Server 2003 [桌面应用 |UWP 应用]
目标平台 窗户
标头 synchapi.h (包括 Windows.h)
Kernel32.lib
DLL Kernel32.dll

另请参阅

WAIT_ABANDONED_0

同步函数

等待函数