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

Этот параметр может быть одним или несколькими из следующих значений.

Сведения об использовании этих значений с объектами, которые остаются сигнальными, см. в разделе Примечания.

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

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Чтобы получить расширенные сведения об ошибке, вызовите
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.

Требования

См. также

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

Группировка потоков в пул

Отмена регистрацииWait

Отмена регистрацииWaitEx

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

WaitOrTimerCallback