Поделиться через

Функция 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, функция возвращается, когда состояние любого из объектов будет сигнализировать. В последнем случае возвращаемое значение указывает объект, состояние которого привело к возврату функции.

[in] dwMilliseconds

Интервал времени ожидания в миллисекундах. Если задано ненулевое значение, функция ожидает, пока указанные объекты не будут сигнализировать, подпрограмма завершения ввода-вывода или APC находится в очереди или интервал истекает. Если dwMilliseconds равно нулю, функция не вводит состояние ожидания, если критерии не выполнены; он всегда возвращается немедленно. Если dwMillisecondsINFINITE, функция возвращается только в том случае, если указанные объекты сигнализируются или выполняется подпрограмма завершения ввода-вывода или APC.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 и Windows Server 2008 R2: значение dwMilliseconds включает время, потраченное в состояниях низкой мощности. Например, время ожидания сохраняет подсчет во время сна компьютера.

Windows 8 и более поздней версии, Windows Server 2012 и более поздней версии: значение dwMilliseconds dwMilliseconds не включает время, затраченное на низкое питание. Например, время ожидания не сохраняет подсчет времени ожидания во время сна компьютера.

[in] bAlertable

Если этот параметр TRUE и поток находится в состоянии ожидания, функция возвращается, когда система очередей подпрограммы завершения ввода-вывода или APC, а поток выполняет подпрограмму или функцию. В противном случае функция не возвращается, а подпрограмма завершения или функция APC не выполняется.

Подпрограмма завершения помещается в очередь при завершении функции ReadFileEx или WriteFileEx. Функция ожидания возвращается и подпрограмма завершения вызывается только в том случае, если bAlertableTRUE, а вызывающий поток — это поток, инициируемый операцией чтения или записи. APC помещается в очередь при вызове QueueUserAPC.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение указывает событие, вызвавшее возвращаемую функцию. Это может быть одно из следующих значений. (Обратите внимание, что WAIT_OBJECT_0 определяется как 0 и WAIT_ABANDONED_0 определяется как 0x000000080L.)

Возврат кода или значения Описание
WAIT_OBJECT_0 (WAIT_OBJECT_0 + nCount– 1)
 Если bWaitAllTRUE, возвращаемое значение в этом диапазоне указывает, что состояние всех указанных объектов сигнализирует.

Если bWaitAllFALSE, возвращаемое значение минус WAIT_OBJECT_0 указывает индекс массива lpHandles массива объекта, удовлетворяющего ожиданию. Если во время вызова сигнализировало несколько объектов, это индекс массива сигнального объекта с наименьшим значением индекса всех сигнальных объектов.
WAIT_ABANDONED_0 (WAIT_ABANDONED_0 + nCount– 1)
 Если bWaitAlltrue, возвращаемое значение в этом диапазоне указывает на то, что состояние всех указанных объектов сигнализируется, а по крайней мере один из объектов является заброшенным объектом мьютекса.

Если bWaitAllFALSE, возвращаемое значение минус WAIT_ABANDONED_0 указывает индекс массива lpHandles заброшенного объекта мьютекса, который удовлетворил ожидание. Владение объектом мьютекса предоставляется вызывающему потоку, а мьютекс имеет значение nonsignalaled.

Если мьютекс защищает сведения о постоянном состоянии, его следует проверить на наличие согласованности.
WAIT_IO_COMPLETION
0x0000000C0L
 Ожидание было завершено одним или несколькими пользовательским режимом асинхронные вызовы процедур (APC) в очередь в поток.
WAIT_TIMEOUT
0x00000102L
 Интервал времени ожидания истек, условия, указанные параметром bWaitAll, не удовлетворены, и подпрограммы завершения не выполняются.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 Сбой функции. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Замечания

Функция WaitForMultipleObjectsEx определяет, выполнены ли критерии ожидания. Если критерии не были выполнены, вызывающий поток вводит состояние ожидания до тех пор, пока не будут выполнены условия условия ожидания или интервал ожидания истекает.

Если bWaitAllTRUE, операция ожидания функции завершается только в том случае, если состояние всех объектов было задано для сигнала. Функция не изменяет состояния указанных объектов до тех пор, пока состояния всех объектов не будут заданы для сигнала. Например, мьютекс может быть сигнален, но поток не получает владение до тех пор, пока состояния других объектов также не будут сигнализировать. В то же время некоторый другой поток может получить владение мьютексом, тем самым задав его состояние незначаемым.

Если bWaitAllFALSE, эта функция проверяет дескрипторы в массиве, начиная с индекса 0, пока один из объектов не будет сигнализован. Если несколько объектов становятся сигнализованными, функция возвращает индекс первого дескриптора в массиве, объект которого был сигнализован.

Функция изменяет состояние некоторых типов объектов синхронизации. Изменение происходит только для объекта или объектов, состояние которого привело к возврату функции. Например, количество объектов семафора уменьшается на один. Дополнительные сведения см. в документации по отдельным объектам синхронизации.

Чтобы ожидать более MAXIMUM_WAIT_OBJECTS дескрипторов, используйте один из следующих методов:

  • Создайте поток для ожидания MAXIMUM_WAIT_OBJECTS дескрипторов, а затем дождитесь этого потока и других дескрипторов. Используйте этот метод для разбиения дескрипторов на группы MAXIMUM_WAIT_OBJECTS.
  • Вызовите RegisterWaitForSingleObject или SetThreadpoolWait, чтобы дождаться каждого дескриптора. Пул потоков эффективно ожидает дескриптора и назначает рабочий поток после того, как объект будет сигнализировать или истекает интервал времени ожидания.
Функция WaitForMultipleObjectsEx может указывать дескриптор любого из следующих типов объектов в массиве lpHandles:
  • Уведомление об изменении
  • Входные данные консоли
  • Событие
  • Уведомление о ресурсе памяти
  • Мьютекс
  • Процесс
  • Семафор
  • Нить
  • Таймер ожидания
Используйте осторожность при вызове функций ожидания и кода, которые напрямую или косвенно создают окна. Если поток создает какие-либо окна, он должен обрабатывать сообщения. Трансляции сообщений отправляются во все окна в системе. Поток, использующий функцию ожидания без интервала времени ожидания, может привести к взаимоблокировке системы. Два примера кода, который косвенно создает окна, являются DDE и функция CoInitialize. Поэтому если у вас есть поток, создающий окна, используйте msgWaitForMultipleObjects или MsgWaitForMultipleObjectsEx, а не WaitForMultipleObjectsEx.

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows XP [классические приложения | Приложения UWP]
минимальный поддерживаемый сервер Windows Server 2003 [классические приложения | Приложения UWP]
целевая платформа Виндоус
заголовка synchapi.h (включая Windows.h в Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
библиотеки Kernel32.lib
DLL Kernel32.dll

См. также

Функции синхронизации

функции ожидания