Функция WaitForMultipleObjectsEx (synchapi.h)
Ожидает, пока один или все указанные объекты не будут помещены в состояние сигнала, подпрограмма завершения ввода-вывода или асинхронный вызов процедуры (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, функция возвращает значение , когда состояние любого из объектов имеет значение signaled. В последнем случае возвращаемое значение указывает объект, состояние которого привело к возврату функции.
[in] dwMilliseconds
Интервал времени ожидания в миллисекундах. Если указано ненулевое значение, функция ожидает, пока не будут поданы сигналы об указанных объектах, подпрограмма завершения ввода-вывода или APC помещается в очередь или истекает интервал. Если значение dwMilliseconds равно нулю, функция не переходит в состояние ожидания, если условия не выполняются; Он всегда возвращается немедленно. Если параметр dwMilliseconds имеет значение INFINITE, функция будет возвращать только в том случае, если указанные объекты будут поставлены в очередь или подпрограмма завершения ввода-вывода или 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 и поток находится в состоянии ожидания, функция возвращает, когда система помещает в очередь подпрограмму завершения ввода-вывода или APC, а поток запускает подпрограмму или функцию. В противном случае функция не возвращается, а подпрограмма завершения или функция APC не выполняется.
Подпрограмма завершения помещается в очередь после завершения функции ReadFileEx или WriteFileEx , в которой она была указана. Функция ожидания возвращает и подпрограмма завершения вызывается только в том случае, если параметр bAlertable имеет значение TRUE , а вызывающий поток является потоком, который инициировал операцию чтения или записи. APC помещается в очередь при вызове QueueUserAPC.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение указывает на событие, вызвавшее возврат функции. Может быть одним из указанных далее. (Обратите внимание, что WAIT_OBJECT_0 определяется как 0, а WAIT_ABANDONED_0 — как 0x00000080L.)
| Возвращаемый код/значение | Описание |
|---|---|
|
Если параметр bWaitAll имеет значение TRUE, возвращаемое значение в этом диапазоне указывает на то, что состояние всех указанных объектов сигнализирует.
Если значение bWaitAll равно FALSE, возвращаемое значение минус WAIT_OBJECT_0 указывает индекс массива lpHandles объекта, удовлетворяющего ожиданию. Если во время вызова подается сигнал о нескольких объектах, это индекс массива для объекта с наименьшим значением индекса из всех сигнальных объектов. |
|
Если параметр bWaitAll имеет значение TRUE, возвращаемое значение в этом диапазоне указывает, что сигнализирует о состоянии всех указанных объектов, и по крайней мере один из объектов является заброшенным объектом мьютекса.
Если параметр bWaitAll имеет значение FALSE, возвращаемое значение минус WAIT_ABANDONED_0 указывает на индекс массива lpHandles заброшенного объекта мьютекса, удовлетворяющего ожиданию. Владение объектом мьютекса предоставляется вызывающему потоку, а мьютексу присваивается значение nonsignaled. Если мьютекс защищал сведения о постоянном состоянии, необходимо проверка их для согласованности. |
|
Ожидание завершилось одним или несколькими вызовами асинхронных процедур в пользовательском режиме (APC), помещенными в очередь в поток. |
|
Истекло время ожидания, условия, заданные параметром bWaitAll , не были выполнены, и подпрограммы завершения не помещаются в очередь. |
|
Сбой функции. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. |
Комментарии
Функция WaitForMultipleObjectsEx определяет, выполнены ли критерии ожидания. Если условия не были выполнены, вызывающий поток переходит в состояние ожидания до тех пор, пока не будут выполнены условия условий ожидания или до истечения интервала времени ожидания.
Если параметр bWaitAll имеет значение TRUE, операция ожидания функции завершается только в том случае, если для состояний всех объектов задано значение signaled. Функция не изменяет состояния указанных объектов до тех пор, пока состояния всех объектов не будут заданы как сигнальные. Например, можно сигнализировать о мьютексе, но поток не получает права владения до тех пор, пока состояния других объектов также не будут заданы как сигнальные. В то же время, некоторые другие потоки могут получить права владения мьютексом, тем самым задав его состояние как nonsignaled.
Если параметр bWaitAll имеет значение FALSE, эта функция проверяет дескрипторы в массиве в порядке, начиная с индекса 0, до тех пор, пока не будет поймечен один из объектов. Если несколько объектов становятся сигнальными, функция возвращает индекс первого дескриптора в массиве, объект которого был сигнализован.
Функция изменяет состояние некоторых типов объектов синхронизации. Изменение происходит только для объекта или объектов, состояние сигнала которых привело к возврату функции. Например, количество объектов семафора уменьшается на один. Дополнительные сведения см. в документации по отдельным объектам синхронизации.
Чтобы дождаться более MAXIMUM_WAIT_OBJECTS дескрипторов, используйте один из следующих методов:
- Создайте поток для ожидания MAXIMUM_WAIT_OBJECTS дескрипторов, а затем дождитесь этого потока и других дескрипторов. Используйте этот метод для разбиения дескрипторов на группы MAXIMUM_WAIT_OBJECTS.
- Вызовите Метод RegisterWaitForSingleObject или SetThreadpoolWait , чтобы дождаться каждого дескриптора. Пул потоков эффективно ожидает дескрипторов и назначает рабочий поток после того, как объект получает сигнал или истекает интервал времени ожидания.
- Уведомление об изменениях
- Входные данные консоли
- Событие
- Уведомление о ресурсе памяти
- Mutex
- Процесс
- Semaphore
- Thread
- Таймер ожидания
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | synchapi.h (включая Windows.h в Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |