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.)

返回代码/值 说明
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，则此范围内的返回值指示所有指定对象的状态已发出信号，并且至少有一个对象是放弃的互斥对象。

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

如果互斥体正在保护永久性状态信息，则应检查它以确保一致性。
WAIT_IO_COMPLETION
0x000000C0L
 等待由一个或多个用户模式 异步过程调用 结束， (APC) 排队到线程。
WAIT_TIMEOUT
0x00000102L
 超时间隔已过， bWaitAll 参数指定的条件未得到满足，并且没有完成例程排队。
WAIT_FAILED
(DWORD) 0xFFFFFFFF
 函数失败。 要获得更多的错误信息，请调用 GetLastError。

注解

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

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

当 bWaitAll 为 FALSE 时，此函数将按从索引 0 开始的顺序检查数组中的句柄，直到向其中一个对象发出信号。 如果多个对象成为信号，该函数将返回数组中第一个句柄的索引，该句柄的对象已发出信号。

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

若要等待多个 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)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

同步函数

Wait 函数