KeWaitForSingleObject 函数 (wdm.h)

项目
02/27/2024

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 纳秒为单位）。

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

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

返回值

KeWaitForSingleObject 可以返回下列值之一。

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

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

注解

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

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

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

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

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

当 WaitMode 参数为 UserMode 或 Alertable 为 TRUE 时，检查 KeWaitForSingleObject 的返回值尤其重要，因为 KeWaitForSingleObject 可能会提前返回状态为 STATUS_USER_APC 或 STATUS_ALERTED。

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

如果可能，Alertable 应设置为 FALSE，WaitMode 应设置为 KernelMode，以降低驱动程序的复杂性。当等待是长期等待时，主要例外。

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

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

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

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

KeWaitForSingleObject 的调用方必须在 IRQL <= DISPATCH_LEVEL 运行。但是，如果 Timeout = NULL 或 Timeout ！= 0，则调用方必须在 IRQL <= APC_LEVEL 并在非比特线程上下文中运行。如果 Timeout ！= NULL 且 Timeout = 0，则调用方必须在 IRQL <= DISPATCH_LEVEL运行。

KeWaitForMutexObject 是转换为 KeWaitForSingleObject 的宏，可以改用它。

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

有关互斥对象的详细信息，请参阅互斥对象。

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	请参见“备注”部分。
DDI 符合性规则	CompleteRequestStatusCheck (wdm) ， HwStorPortProhibitedDDi (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)