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


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

Сигнализирует об одном объекте и ожидает другого объекта в виде одной операции.

Синтаксис

DWORD SignalObjectAndWait(
  [in] HANDLE hObjectToSignal,
  [in] HANDLE hObjectToWaitOn,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

Параметры

[in] hObjectToSignal

Дескриптор объекта для передачи сигнала. Этот объект может быть семафором, мьютексом или событием.

Если дескриптор является семафором, требуется право доступа SEMAPHORE_MODIFY_STATE . Если дескриптор является событием, требуется право доступа EVENT_MODIFY_STATE . Если дескриптор является мьютексом, а вызывающий объект не является владельцем мьютекса, функция завершается сбоем с ERROR_NOT_OWNER.

[in] hObjectToWaitOn

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

[in] dwMilliseconds

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

[in] bAlertable

Если этот параметр имеет значение TRUE, функция возвращает, когда система помещает в очередь подпрограмму завершения ввода-вывода или функцию APC, а поток вызывает функцию. Если значение РАВНО FALSE, функция не возвращает, а поток не вызывает подпрограмму завершения или функцию APC.

Подпрограмма завершения помещается в очередь после завершения вызова функции, который поставил в очередь APC. Эта функция возвращает и подпрограмма завершения вызывается только в том случае, если параметр bAlertable имеет значение TRUE, а вызывающий поток является потоком, который помещал APC в очередь.

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

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

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

Если мьютекс защищал сведения о постоянном состоянии, следует проверка их для согласованности.

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

Комментарии

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

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

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

Поток может использовать функцию SignalObjectAndWait , чтобы убедиться, что рабочий поток находится в состоянии ожидания перед сигналом объекта. Например, поток и рабочий поток могут использовать дескрипторы для объектов событий для синхронизации своей работы. Поток выполняет следующий код:

  dwRet = WaitForSingleObject(hEventWorkerDone, INFINITE);
  if( WAIT_OBJECT_0 == dwRet)
    SetEvent(hEventMoreWorkToDo);

Рабочий поток выполняет следующий код:

  dwRet = SignalObjectAndWait(hEventWorkerDone,
                              hEventMoreWorkToDo,
                              INFINITE, 
                              FALSE);

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

Соблюдайте особую осторожность при использовании SignalObjectAndWait и PulseEvent с Windows 7, так как использование этих API в нескольких потоках может привести к взаимоблокировке приложения. Потоки, передаваемые сигналом SignalObjectAndWait , вызывают PulseEvent , чтобы сообщить об объекте ожидания вызова SignalObjectAndWait . В некоторых случаях вызывающий объект SignalObjectAndWait не может вовремя получить состояние сигнала ожидающего объекта, что приводит к взаимоблокировке.

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

Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0400 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.

Требования

Требование Значение
Минимальная версия клиента Windows XP [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2003 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header synchapi.h (включая Windows.h)
Библиотека Kernel32.lib
DLL Kernel32.dll

См. также

MsgWaitForMultipleObjects

MsgWaitForMultipleObjectsEx

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

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