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

Статья
11/08/2024

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

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

Синтаксис

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

Параметры

[in] hHandle

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

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

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

[in] dwMilliseconds

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

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

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

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

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

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

Замечания

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

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

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

Уведомление об изменении
Входные данные консоли
Событие
Уведомление о ресурсе памяти
Мьютекс
Процесс
Семафор
Нить
Таймер ожидания

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

Примеры

Пример см. в разделе Using Mutex Objects.

Требования

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

См. также

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

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

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