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

Статья
03/02/2024

Ожидает, пока указанный объект не перейдет в состояние сигнала или не истедет интервал времени ожидания.

Чтобы ввести состояние ожидания с оповещениями, используйте функцию WaitForSingleObjectEx . Чтобы дождаться нескольких объектов, используйте WaitForMultipleObjects.

Синтаксис

DWORD WaitForSingleObject(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds
);

Параметры

[in] hHandle

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

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

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

[in] dwMilliseconds

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

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 не включает время, затраченное на малое энергопотребление Государств. Например, время ожидания не продолжает отсчитывать, пока компьютер находится в спятом режиме.

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

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

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

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

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

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

Уведомление об изменениях
Входные данные консоли
Событие
Уведомление о ресурсе памяти
Mutex
Процесс
Semaphore
Thread
Таймер ожидания

Будьте внимательны при вызове функций ожидания и кода, которые прямо или косвенно создают окна. Если поток создает какие-либо окна, он должен обрабатывать сообщения. Широковещательные сообщения отправляются во все окна в системе. Поток, использующий функцию ожидания без интервала ожидания, может привести к взаимоблокировке системы. Два примера кода, который косвенно создает окна, — это DDE и функция CoInitialize . Поэтому при наличии потока, создающего окна, используйте msgWaitForMultipleObjects или MsgWaitForMultipleObjectsEx, а не WaitForSingleObject.

Примеры

Пример см. в разделе Использование объектов мьютекса.

Требования

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

См. также

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

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

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