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

Статья
03/08/2023

Подпрограмма 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 г. Отрицательное значение указывает интервал относительно текущего времени. Абсолютное время истечения срока действия отслеживает любые изменения системного времени; Изменения системного времени не влияют на относительный срок действия.

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

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

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

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

Код возврата	Описание
STATUS_SUCCESS	Объект диспетчера, заданный параметром Object , выполнил ожидание.
STATUS_ALERTED	Ожидание было прервано, чтобы доставить оповещение в вызывающий поток.
STATUS_USER_APC	Ожидание прервано для доставки пользовательского асинхронного вызова процедур (APC) в вызывающий поток.
STATUS_TIMEOUT	Время ожидания истекло до того, как объект был установлен в состояние сигнала. Это значение может быть возвращено, если указанный набор условий ожидания не может быть немедленно выполнен, а время ожидания равно нулю.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	См. раздел "Примечания".
Правила соответствия DDI	CompleteRequestStatusCheck(wdm), HwStorPortProhibitedDIs(storport), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), IrpProcessingComplete(wdm), IrqlKeWaitForMutexObject(wdm), LowerDriverReturn(wdm), MarkIrpPending2(wdm), PendedCompletedRequest(wdm), PendedCompletedRequest2(wdm), PendedCompletedRequest3(wdm), PendedCompletedRequestEx(wdm), RemoveLockForwardDeviceControl(wdm), RemoveLockForwardDeviceControlInternal(wdm), RemoveLockForwardRead(wdm), RemoveLockForwardWrite(wdm), SpNoWait(storport), StartDeviceWait(wdm), StartDeviceWait2(wdm), StartDeviceWait3(wdm), StartDeviceWait4(wdm)