Функция 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 включает время, потраченное в состояниях низкой мощности. Например, время ожидания сохраняет подсчет во время сна компьютера.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение указывает событие, вызвавшее возвращаемую функцию. Это может быть одно из следующих значений. (Обратите внимание, что WAIT_OBJECT_0 определяется как 0 и WAIT_ABANDONED_0 определяется как 0x000000080L.)
| Возврат кода или значения | Описание |
|---|---|
|
Если bWaitAllTRUE, возвращаемое значение в указанном диапазоне указывает, что состояние всех указанных объектов сигнализирует.
Если bWaitAllFALSE, возвращаемое значение минус WAIT_OBJECT_0 указывает индекс массива lpHandles массива объекта, удовлетворяющего ожиданию. Если во время вызова сигнализировало несколько объектов, это индекс массива сигнального объекта с наименьшим значением индекса всех сигнальных объектов. |
|
Если bWaitAllTRUE, возвращаемое значение в указанном диапазоне указывает, что состояние всех указанных объектов сигнализирует, а по крайней мере один из объектов является заброшенным объектом мьютекса.
Если bWaitAllFALSE, возвращаемое значение минус WAIT_ABANDONED_0 указывает индекс массива lpHandles заброшенного объекта мьютекса, который удовлетворил ожидание. Владение объектом мьютекса предоставляется вызывающему потоку, а мьютекс имеет значение nonsignalaled. Если мьютекс защищает сведения о постоянном состоянии, его следует проверить на наличие согласованности. |
|
Интервал времени ожидания истек и условия, указанные параметром bWaitAll, не удовлетворены. |
|
Сбой функции. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError. |
Замечания
Функция waitForMultipleObjects
Если bWaitAllTRUE, операция ожидания функции завершается только в том случае, если состояние всех объектов было задано для сигнала. Функция не изменяет состояния указанных объектов до тех пор, пока состояния всех объектов не будут заданы для сигнала. Например, мьютекс может быть сигнален, но поток не получает владение до тех пор, пока состояния других объектов также не будут сигнализировать. В то же время некоторый другой поток может получить владение мьютексом, тем самым задав его состояние незначаемым.
Если bWaitAllFALSE, эта функция проверяет дескрипторы в массиве, начиная с индекса 0, пока один из объектов не будет сигнализован. Если несколько объектов становятся сигнализованными, функция возвращает индекс первого дескриптора в массиве, объект которого был сигнализован.
Функция изменяет состояние некоторых типов объектов синхронизации. Изменение происходит только для объекта или объектов, состояние которого привело к возврату функции. Например, количество объектов семафора уменьшается на один. Дополнительные сведения см. в документации по отдельным объектам синхронизации.
Чтобы ожидать более MAXIMUM_WAIT_OBJECTS дескрипторов, используйте один из следующих методов:
- Создайте поток для ожидания MAXIMUM_WAIT_OBJECTS дескрипторов, а затем дождитесь этого потока и других дескрипторов. Используйте этот метод для разбиения дескрипторов на группы MAXIMUM_WAIT_OBJECTS.
- Вызовите RegisterWaitForSingleObject или SetThreadpoolWait, чтобы дождаться каждого дескриптора. Пул потоков эффективно ожидает дескриптора и назначает рабочий поток после того, как объект будет сигнализировать или истекает интервал времени ожидания.
- Уведомление об изменении
- Входные данные консоли
- Событие
- Уведомление о ресурсе памяти
- Мьютекс
- Процесс
- Семафор
- Нить
- Таймер ожидания
Примеры
Пример см. в разделе Ожидание нескольких объектов.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows XP [классические приложения | Приложения UWP] |
| минимальный поддерживаемый сервер | Windows Server 2003 [классические приложения | Приложения UWP] |
| целевая платформа | Виндоус |
| заголовка | synchapi.h (включая Windows.h) |
| библиотеки |
Kernel32.lib |
| DLL | Kernel32.dll |