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

Функция WaitForSingleObjectEx (synchapi.h)

  • Статья

Ожидает, пока указанный объект находится в сигнальном состоянии, подпрограмма завершения ввода-вывода или асинхронный вызов процедуры (APC) помещается в поток или истекает интервал времени ожидания.

Чтобы дождаться нескольких объектов, используйте WaitForMultipleObjectsEx.

Синтаксис

DWORD WaitForSingleObjectEx(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

Параметры

[in] hHandle

Дескриптор объекта. Список типов объектов, дескриптор которых можно указать, см. в следующем разделе "Примечания".

Если этот дескриптор закрыт, пока ожидание по-прежнему ожидается, поведение функции не определено.

Дескриптор должен иметь право доступа SYNCHRONIZE. Дополнительные сведения см. в стандартных прав доступа.

[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_ABANDONED
0x00000080L
 Указанный объект — это объект мьютекса, который не был выпущен потоком, принадлежащим объекту мьютекса до завершения собственного потока. Владение объектом мьютекса предоставляется вызывающему потоку, а мьютекс имеет значение nonsignaled.

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

Замечания

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

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

Функция WaitForSingleObjectEx может ожидать следующих объектов:

  • Уведомление об изменении
  • Входные данные консоли
  • Событие
  • Уведомление о ресурсе памяти
  • Мьютекс
  • Процесс
  • Семафор
  • Нить
  • Таймер ожидания
Используйте осторожность при вызове функций ожидания и кода, которые напрямую или косвенно создают окна. Если поток создает какие-либо окна, он должен обрабатывать сообщения. Трансляции сообщений отправляются во все окна в системе. Поток, использующий функцию ожидания без интервала времени ожидания, может привести к взаимоблокировке системы. Два примера кода, который косвенно создает окна, являются DDE и функция CoInitialize. Таким образом, если у вас есть поток, создающий окна, используйте MsgWaitForMultipleObjects или MsgWaitForMultipleObjectsEx, а не WaitForSingleObjectEx.

Примеры

Пример см. в разделе Именованный сервер конвейера с помощью подпрограмм завершения.

Требования

Требование Ценность
минимальные поддерживаемые клиентские 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

См. также

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

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