WaitForMultipleObjectsEx 函数 (synchapi.h)

项目
08/26/2023

等待一个或所有指定的对象处于信号状态、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 函数

通过

WaitForMultipleObjectsEx 函数 (synchapi.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源