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

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

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

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

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

Комментарии

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

Параметр 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, который можно использовать вместо него.

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

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

Требования

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

ExInitializeFastMutex

KeBugCheckEx

KeInitializeEvent

KeInitializeMutex

KeInitializeSemaphore

KeInitializeTimer

KeWaitForMultipleObjects