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

  • Статья

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

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

Синтаксис

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

Параметры

[in] hHandle

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

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

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

[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 , в которой она была указана. Функция wait возвращается, а подпрограмма завершения вызывается только в том случае, если bAlertable имеет значение TRUE, а вызывающим потоком является поток, инициирующий операцию чтения или записи. APC помещается в очередь при вызове QueueUserAPC.

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

Если функция выполнена успешно, возвращаемое значение указывает на событие, вызвавшее возврат функции. Может быть одним из указанных далее.

Возвращаемый код или значение Описание
WAIT_ABANDONED
0x00000080L
 Указанный объект — это объект мьютекса, который не был освобожден потоком, владельцем объекта мьютекса до завершения владеющего потока. Владение объектом мьютекса предоставляется вызывающему потоку, а мьютексу присваивается значение без знака.

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

Комментарии

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

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

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

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

Примеры

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

Требования

Требование Значение
Минимальная версия клиента 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

См. также

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

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