Функция KeWaitForSingleObject (wdm.h)

Подпрограмма KeWaitForSingleObject помещает текущий поток в состояние ожидания, пока заданный объект диспетчера не установлен в сигнальное состояние или (при необходимости) до истечения времени ожидания.

Синтаксис

NTSTATUS
KeWaitForSingleObject (
    PVOID Object,
    KWAIT_REASON WaitReason,
    KPROCESSOR_MODE WaitMode,
    BOOLEAN Alertable,
    PLARGE_INTEGER Timeout
    );

Параметры

[in] Object

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

[in] WaitReason

Указывает причину ожидания. Драйвер должен задать значение Executive, если он не выполняет работу от имени пользователя и работает в контексте потока пользователя, в этом случае он должен задать это значение в UserRequest.

[in] WaitMode

Указывает, ожидает ли вызывающий объект в KernelMode или UserMode. Для наименьшего уровня и промежуточных драйверов следует указать KernelMode. Если данный объект является мьютексом, вызывающий объект должен указать KernelMode.

[in] Alertable

Указывает логическое значение, которое имеет значение TRUE , если ожидание оповещается и false в противном случае.

[in, optional] Timeout

Указатель на значение времени ожидания, указывающее абсолютное или относительное время в 100-наносекундах единиц, в которых ожидается завершение ожидания.

Положительное значение указывает абсолютное время относительно 1 января 1601 года. Отрицательное значение указывает интервал относительно текущего времени. Абсолютное время истечения срока действия отслеживает любые изменения в системном времени; относительные сроки действия не влияют на изменения системного времени.

Если *Timeout = 0, подпрограмма возвращается без ожидания. Если вызывающий объект предоставляет указатель NULL , подпрограмма ожидает неограниченное время, пока объект диспетчера не будет задано сигнальное состояние. Дополнительные сведения см. в следующем разделе "Примечания".

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

KeWaitForSingleObject может вернуть одно из следующих элементов.

Макрос NT_SUCCESS распознает все эти значения состояния как "успешно".

Замечания

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

Параметр alertable определяет, когда поток может быть оповещен и его состояние ожидания, следовательно, прервано. Дополнительные сведения см. в разделе "Ожидание" и "API".

Особое внимание следует учитывать, когда параметр Object , переданный в KeWaitForSingleObject , является мьютексом. Если объект диспетчера ждал мьютекса, доставка APC совпадает со всеми другими объектами диспетчера во время ожидания. Однако после возвращения KeWaitForSingleObject с STATUS_SUCCESS и потоком фактически содержит мьютекс, доставляются только специальные API режима ядра. Доставка всех остальных API, как в режиме ядра, так и в пользовательском режиме, отключена. Это ограничение на доставку API сохраняется до тех пор, пока мьютекс не будет освобожден.

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

Если параметр WaitMode является UserMode, стек ядра можно переключить во время ожидания. Следовательно, вызывающий объект никогда не должен пытаться передавать параметры в стеке при вызове KeWaitForSingleObject с помощью аргумента UserMode . Если вы выделяете событие в стеке, необходимо задать для параметра WaitMode значение KernelMode.

Особенно важно проверить возвращаемое значение KeWaitForSingleObject , если параметр WaitMode — UserMode или Alertable имеет значение TRUE, так как KeWaitForSingleObject может вернуться рано с состоянием STATUS_USER_APC или STATUS_ALERTED.

Все долгосрочные ожидания, которые могут быть прерваны пользователем, должны быть ожиданием UserMode и оповещения должны иметь значение FALSE.

По возможности для уменьшения сложности драйвера необходимо задать значениеFALSE и WaitMode. Основное исключение заключается в том, что ожидание является долгосрочным ожиданием.

Если указатель NULL предоставляется для timeout, вызывающий поток остается в состоянии ожидания, пока объект не будет сигнализировать.

Значение времени ожидания равно нулю позволяет проверять набор условий ожидания и для условной производительности любых побочных эффектов, если ожидание может быть немедленно удовлетворено, как при приобретении мьютекса.

Интервалы времени ожидания измеряются относительно системных часов, а точность, с которой операционная система может обнаруживать конец интервала времени ожидания, ограничивается степенью детализации системных часов. Дополнительные сведения см. в разделе "Точность таймера".

Мьютекс может быть рекурсивно приобретен только во время MINLONG. Если это ограничение превышено, подпрограмма вызывает исключение STATUS_MUTANT_LIMIT_EXCEEDED.

Вызывающие объекты KeWaitForSingleObject должны работать в IRQL <= DISPATCH_LEVEL. Однако если значение timeout = NULL или *Timeout != 0, вызывающий объект должен выполняться в IRQL <= APC_LEVEL и в контексте непарбитарного потока. Если время ожидания != NULL и *Timeout = 0, вызывающий объект должен работать в IRQL <= DISPATCH_LEVEL.

KeWaitForMutexObject — это макрос, который преобразуется в KeWaitForSingleObject, который можно использовать вместо этого.

Для повышения производительности используйте быстрые мьютекси или защищенные мьютексы. Дополнительные сведения см. в разделе "Альтернатива объектам Мьютекса".

Дополнительные сведения об объектах мьютекса см. в разделе "Объекты Мьютекса".

Требования

См. также

ExInitializeFastMutex

KeBugCheckEx

KeInitializeEvent

KeInitializeMutex

KeInitializeSemaphore

KeInitializeTimer

KeWaitForMultipleObjects