Функция 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 распознает все эти значения состояния как "успех".

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

Комментарии

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

   
Минимальная версия клиента Доступно начиная с Windows 2000.
Целевая платформа Универсальное
Заголовок wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Библиотека NtosKrnl.lib
DLL NtosKrnl.exe
IRQL См. раздел "Примечания".
Правила соответствия DDI CompleteRequestStatusCheck(wdm), HwStorPortProhibitedDDIs(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), SpNoWait(storport), StartDeviceWait(wdm), StartDeviceWait2(wdm), StartDeviceWait3(wdm), StartDeviceWait4(wdm)

См. также раздел

ExInitializeFastMutex

KeBugCheckEx

KeInitializeEvent

KeInitializeMutex

KeInitializeSemaphore

KeInitializeTimer

KeWaitForMultipleObjects