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


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

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

Чтобы ввести состояние ожидания с оповещениями, используйте функцию 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

См. также

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

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