KeWaitForSingleObject 函数 (wdm.h)

KeWaitForSingleObject 例程将当前线程置于等待状态,直到给定调度程序对象设置为信号状态,或者可以选择 () ,直到等待超时。

语法

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

parameters

[in] Object

指向初始化的调度程序对象 (事件、互斥体、信号灯、线程或计时器) 的指针,调用方为其提供存储。 调度程序对象必须驻留在非分页系统内存中。 有关详细信息,请参阅“备注”。

[in] WaitReason

指定等待的原因。 驱动程序应将此值设置为 Executive,除非它代表用户执行工作并在用户线程的上下文中运行,在这种情况下,应将此值设置为 UserRequest

[in] WaitMode

指定调用方是在 KernelMode 还是 UserMode 中等待。 最低级别和中间驱动程序应指定 KernelMode。 如果给定 对象 是互斥体,则调用方必须指定 KernelMode

[in] Alertable

指定一个布尔值,如果等待是可警报的,则为 TRUE ;否则为 FALSE

[in, optional] Timeout

指向一个超时值,该值指定 100 纳秒单位中的绝对时间或相对时间,在该单位中等待完成。

正值指定相对于 1601 年 1 月 1 日绝对时间。 负值指定相对于当前时间的间隔。 绝对过期时间跟踪系统时间中的任何更改;相对过期时间不受系统时间更改的影响。

如果 *Timeout = 0,则例程返回而不等待。 如果调用方提供 NULL 指针,则例程将无限期等待,直到调度程序对象设置为信号状态。 有关更多信息,请参见下面的“备注”部分。

返回值

KeWaitForSingleObject 可以返回以下项之一。

注意

NT_SUCCESS宏会将所有这些状态值识别为“成功”值。

返回代码 说明
STATUS_SUCCESS Object 参数指定的调度程序对象满足等待。
STATUS_ALERTED 等待中断,向调用线程发送警报。
STATUS_USER_APC 等待中断, (APC) 传送到调用线程的用户异步过程调用。
STATUS_TIMEOUT 在对象设置为信号状态之前发生超时。 当无法立即满足指定的等待条件集并且 超时 设置为零时,可以返回此值。

备注

检查指定的 对象的 当前状态,以确定是否可以立即满足等待。 如果是这样,则对对象执行必要的副作用。 否则,当前线程处于等待状态,并且选择新线程以在当前处理器上执行。

Alertable 参数确定线程何时可以发出警报,以及其等待状态因此中止。 有关详细信息,请参阅 Waits 和 APC

当传递给 KeWaitForSingleObject的对象参数是互斥体时,需要特别注意。 如果等待的调度程序对象是互斥体,则 APC 传递与 等待期间所有其他调度程序对象相同。 但是, 在 KeWaitForSingleObject 返回STATUS_SUCCESS且线程实际保存互斥体后,仅传递特殊的内核模式 APC。 禁用了所有其他 APC(内核模式和用户模式)的传递。 在释放互斥体之前,对 APC 传递的限制仍然存在。

Object 参数指向的调度程序对象必须驻留在非分页系统内存中。

如果 WaitMode 参数为 UserMode,则可以在等待期间交换内核堆栈。 因此,调用方在使用 UserMode 参数调用 KeWaitForSingleObject,绝不会尝试在堆栈上传递参数。 如果在堆栈上分配事件,则必须将 WaitMode 参数设置为 KernelMode

WaitMode 参数为 UserModeAlertableTRUE 时,检查 KeWaitForSingleObject 的返回值尤其重要,因为 KeWaitForSingleObject 可能提前返回状态为 STATUS_USER_APC 或 STATUS_ALERTED。

用户可中止的所有长期等待应为 UserMode 等待, 并且 Alertable 应设置为 FALSE

如果可能,警报应设置为 FALSEWaitMode 应设置为 KernelMode,以减少驱动程序复杂性。 此情况的主要例外是等待是长期等待。

如果为 Timeout 提供了 NULL 指针,则调用线程将保持等待状态,直到发出对象信号。

如果可以立即满足等待条件,则超时值允许测试一组等待条件,并满足任何副作用的条件性能,就像获取互斥体一样。

超时间隔相对于系统时钟进行测量,操作系统可以检测到超时间隔结束的准确性受系统时钟粒度的限制。 有关详细信息,请参阅 计时器准确性

互斥体只能递归获取 MINLONG 时间。 如果超出此限制,则例程将引发STATUS_MUTANT_LIMIT_EXCEEDED异常。

KeWaitForSingleObject 的调用方必须在 IRQL <= DISPATCH_LEVEL运行。 但是,如果超时NULL 或 *Timeout = != 0,则调用方必须在 IRQL<= APC_LEVEL和非比特线程上下文中运行。 (如果 Timeout != NULL 和 *Timeout = 0,则调用方必须在 IRQL <= DISPATCH_LEVEL.)

KeWaitForMutexObject 是转换为 KeWaitForSingleObject 的宏,可以改用该宏。

为了获得更好的性能,请使用快速互斥体或受保护的互斥体。 有关详细信息,请参阅 Mutex 对象的替代项

有关互斥对象的详细信息,请参阅 Mutex 对象

要求

   
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 wdm.h(包括 Wdm.h、Ntddk.h、Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL 请参阅“备注”部分。
DDI 符合性规则 CompleteRequestStatusCheck (wdm) HwStorPortProhibitedDDDIs (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)

请参阅

ExInitializeFastMutex

KeBugCheckEx

KeInitializeEvent

KeInitializeMutex

KeInitializeSemaphore

KeInitializeTimer

KeWaitForMultipleObjects