Функция 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 в очередь.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение указывает на событие, вызвавшее возврат функции. Может быть одним из указанных далее.
| Возвращаемый код/значение | Описание |
|---|---|
|
Указанный объект является объектом мьютекса, который не был освобожден потоком, владельцем объекта мьютекса до завершения владеющего потока. Владение объектом мьютекса предоставляется вызывающему потоку, а мьютексу присваивается значение nonsignaled.
Если мьютекс защищал сведения о постоянном состоянии, следует проверка их для согласованности. |
|
Ожидание завершилось одним или несколькими вызовами асинхронных процедур в пользовательском режиме (APC), помещенными в очередь в поток. |
|
Состояние указанного объекта сигнализируется. |
|
Истекло время ожидания, а состояние объекта не соответствует знакам. |
|
Сбой функции. Дополнительные сведения об ошибке можно получить, вызвав 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 |
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по