Функция RegisterWaitForSingleObject (winbase.h)
Направляет поток ожидания в пуле потоков на ожидание объекта . Поток ожидания помещает в очередь указанную функцию обратного вызова в пул потоков при выполнении одного из следующих действий:
- Указанный объект находится в состоянии сигнала.
- Истекает интервал времени ожидания.
Синтаксис
BOOL RegisterWaitForSingleObject(
[out] PHANDLE phNewWaitObject,
[in] HANDLE hObject,
[in] WAITORTIMERCALLBACK Callback,
[in, optional] PVOID Context,
[in] ULONG dwMilliseconds,
[in] ULONG dwFlags
);
Параметры
[out] phNewWaitObject
Указатель на переменную, которая получает дескриптор ожидания при возврате. Обратите внимание, что дескриптор ожидания нельзя использовать в функциях, которым требуется дескриптор объекта, например CloseHandle.
[in] hObject
Дескриптор объекта . Список типов объектов, дескрипторов которых можно указать, см. в следующем разделе Примечания.
Если этот дескриптор закрыт, пока ожидание еще не завершено, поведение функции не определено.
Дескрипторы должны иметь право доступа SYNCHRONIZE . Дополнительные сведения см. в разделе Стандартные права доступа.
[in] Callback
Указатель на определяемую приложением функцию типа WAITORTIMERCALLBACK , выполняемую, когда hObject находится в состоянии сигнала или dwMilliseconds истекает. Дополнительные сведения см. в разделе WaitOrTimerCallback.
[in, optional] Context
Одно значение, передаваемое функции обратного вызова.
[in] dwMilliseconds
Интервал времени ожидания в миллисекундах. Функция возвращает значение, если интервал истекает, даже если состояние объекта не имеет знака. Если значение dwMilliseconds равно нулю, функция проверяет состояние объекта и возвращает немедленно. Если dwMilliseconds имеет значение INFINITE, интервал времени ожидания функции никогда не истекает.
[in] dwFlags
Этот параметр может быть одним или несколькими из следующих значений.
Сведения об использовании этих значений с объектами, которые остаются сигнальными, см. в разделе Примечания.
| Значение | Значение |
|---|---|
|
По умолчанию функция обратного вызова помещается в очередь в рабочий поток, отличный от ввода-вывода. |
|
Этот флаг не используется.
Windows Server 2003 и Windows XP: Функция обратного вызова помещается в очередь в рабочий поток ввода-вывода. Этот флаг следует использовать, если функция должна выполняться в потоке, который ожидает оповещения. Рабочие потоки ввода-вывода были удалены начиная с Windows Vista и Windows Server 2008. |
|
Функция обратного вызова помещается в очередь в поток, который никогда не завершается. Это не гарантирует, что один и тот же поток будет использоваться каждый раз. Этот флаг следует использовать только для коротких задач, иначе это может повлиять на другие операции ожидания.
Этот флаг необходимо установить, если поток вызывает функции, использующие APC. Дополнительные сведения см. в разделе Асинхронные вызовы процедур. Обратите внимание, что в настоящее время ни один рабочий поток не является действительно постоянным, хотя ни один рабочий поток не завершит работу при наличии ожидающих запросов ввода-вывода. |
|
Функция обратного вызова вызывается самим потоком ожидания. Этот флаг следует использовать только для коротких задач, иначе это может повлиять на другие операции ожидания.
Взаимоблокировки могут возникать, если какой-либо другой поток получает монопольную блокировку и вызывает функцию UnregisterWait или UnregisterWaitEx , пока функция обратного вызова пытается получить ту же блокировку. |
|
Функция обратного вызова может выполнять длительное ожидание. Этот флаг помогает системе решить, следует ли создавать новый поток. |
|
Поток больше не будет ожидать дескриптора после вызова функции обратного вызова один раз. В противном случае таймер сбрасывается каждый раз, когда операция ожидания завершается, пока операция ожидания не будет отменена. |
|
Функции обратного вызова будут использовать текущий маркер доступа, будь то маркер процесса или маркер олицетворения. Если этот флаг не указан, функции обратного вызова выполняются только с маркером процесса.
Windows XP: Этот флаг не поддерживается до Windows XP с пакетом обновления 2 (SP2) и Windows Server 2003. |
Возвращаемое значение
Если функция выполняется успешно, возвращается ненулевое значение.
Если функция выполняется неудачно, возвращается нулевое значение. Чтобы получить расширенные сведения об ошибке, вызовите
GetLastError.
Комментарии
При необходимости новые потоки ожидания создаются автоматически. Операция ожидания выполняется потоком ожидания из пула потоков. Подпрограмма обратного вызова выполняется рабочим потоком, когда состояние объекта становится сигнальным или истекает интервал времени ожидания. Если dwFlags не WT_EXECUTEONLYONCE, таймер сбрасывается при каждом сигнале о событии или истечении интервала ожидания.
После завершения ожидания необходимо вызвать функцию UnregisterWait или UnregisterWaitEx , чтобы отменить операцию ожидания. (Даже операции ожидания, использующие WT_EXECUTEONLYONCE , должны быть отменены.) Не делайте блокирующий вызов любой из этих функций из функции обратного вызова.
Обратите внимание, что не следует импульсировать объект события, передаваемый в RegisterWaitForSingleObject, так как поток ожидания может не обнаружить, что событие подается до сброса. Не следует регистрировать объект, который остается сигнальным (например, событие сброса вручную или завершенный процесс), если не установлен флаг WT_EXECUTEONLYONCE или WT_EXECUTEINWAITTHREAD . Для других флагов функция обратного вызова может вызываться слишком много раз до сброса события.
Функция изменяет состояние некоторых типов объектов синхронизации. Изменение происходит только для объекта, состояние которого привело к выполнению условия ожидания. Например, количество объектов семафора уменьшается на единицы.
Функция RegisterWaitForSingleObject может ожидать следующих объектов:
- Уведомление об изменениях
- Входные данные консоли
- Событие
- Уведомление о ресурсе памяти
- Mutex
- Процесс
- Semaphore
- Thread
- Таймер для ожидания
По умолчанию пул потоков содержит не более 500 потоков. Чтобы увеличить это ограничение, используйте макрос WT_SET_MAX_THREADPOOL_THREAD , определенный в WinNT.h.
#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
((Flags)|=(Limit)<<16)
Используйте этот макрос при указании параметра dwFlags . Параметры макроса — это нужные флаги и новое ограничение (до (2<<16)-1 потоков). Однако обратите внимание, что приложение может повысить производительность, сохраняя низкое количество рабочих потоков.
Рабочий элемент и все вызываемые им функции должны быть безопасными в пуле потоков. Поэтому нельзя вызвать асинхронный вызов, требующий постоянного потока, например функции RegNotifyChangeKeyValue , из среды обратного вызова по умолчанию. Вместо этого задайте максимальный размер пула потоков, равный минимальному значению пула потоков, с помощью функций SetThreadPoolThreadMaximum и SetThreadpoolThreadMinimum или создайте собственный поток с помощью функции CreateThread . (Для исходного API пула потоков укажите WT_EXECUTEINPERSISTENTTHREAD с помощью функции QueueUserWorkItem .)
Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0500 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbase.h (включая Windows.h) |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по