Функция 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 в очередь.

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

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

Комментарии

Функция 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.

Требования

См. также

MsgWaitForMultipleObjects

MsgWaitForMultipleObjectsEx

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

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