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
指定一个布尔值 ，如果等待可发出警报且 FALSE，则为 TRUE。
[in, optional] Timeout
指向一个超时值的指针，该值指定以 100 纳秒为单位的绝对时间或相对时间，等待完成。
正值指定相对于 1601 年 1 月 1 日绝对时间。 负值指定相对于当前时间的间隔。 绝对过期时间跟踪系统时间中的任何更改;相对过期时间不受系统时间更改的影响。
如果 超时 = 0，则例程返回而不等待。 如果调用方提供 NULL 指针，则例程将无限期等待，直到调度程序对象设置为信号状态。 有关详细信息，请参阅以下“备注”部分。
返回值
KeWaitForSingleObject 可以返回以下项之一。
NT_SUCCESS宏会将所有这些状态值识别为“成功”值。
| 返回代码 | 描述 |
|---|---|
| STATUS_SUCCESS | Object 参数指定的调度程序对象满足等待。 |
| STATUS_ALERTED | 等待中断，将警报传送到调用线程。 |
| STATUS_USER_APC | 等待中断，将用户异步过程调用 （APC） 传递到调用线程。 |
| STATUS_TIMEOUT | 在对象设置为信号状态之前发生超时。 当无法立即满足指定的等待条件集并且 超时 设置为零时，可以返回此值。 |
言论
检查指定的 对象 的当前状态，以确定是否可以立即满足等待。 如果是，则对对象执行必要的副作用。 否则，当前线程处于等待状态，并且已选择新线程以便在当前处理器上执行。
Alertable 参数确定线程何时可以发出警报及其等待状态，从而中止。 有关详细信息，请参阅 等待和 APC。
当传递给 KeWaitForSingleObject 的 Object 参数是互斥体时，需要特别考虑一下。 如果等待的调度程序对象是互斥体，则 APC 传递与等待期间所有其他调度程序对象的传递相同。 但是，在 KeWaitForSingleObject 返回STATUS_SUCCESS并且线程实际保存互斥体后，只传递特殊的内核模式 APC。 禁用了所有其他 APC（内核模式和用户模式）的传递。 在释放互斥体之前，对 APC 传递的这种限制会一直存在。
Object 参数指向的调度程序对象必须驻留在非分页系统内存中。
如果 WaitMode 参数 UserMode，则可以在等待期间交换内核堆栈。 因此，调用方在使用 UserMode 参数调用 KeWaitForSingleObject 时，决不能尝试在堆栈上传递参数。 如果在堆栈上分配事件，则必须将 WaitMode 参数设置为 KernelMode。
当 WaitMode 参数 userMode 或 时，检查 KeWaitForSingleObject 的返回值尤其重要可警报TRUE，因为 KeWaitForSingleObject 可能提前返回状态为STATUS_USER_APC或STATUS_ALERTED。
用户可中止的所有长期等待应 UserMode 等待，可警报 应设置为 FALSE。
如果可能，应将 可警报 设置为 FALSE，WaitMode 应设置为 KernelMode，以减少驱动程序复杂性。 此情况的主要例外是等待是长期等待。
如果为 超时提供 NULL 指针，则调用线程将保持等待状态，直到发出 对象 信号。
如果可以立即满足等待条件，则超时值为零允许测试一组等待条件，以及满足任何副作用的条件性能，就像在获取互斥体时一样。
超时间隔相对于系统时钟进行度量，作系统可以检测超时间隔结束的准确性受系统时钟粒度的限制。 有关详细信息，请参阅 计时器准确性。
互斥体只能递归获取 MINLONG 时间。 如果超出此限制，则例程将引发STATUS_MUTANT_LIMIT_EXCEEDED异常。
KeWaitForSingleObject 的调用方必须在 IRQL <= DISPATCH_LEVEL 上运行。 但是，如果 超时 = NULL 或 超时 ！= 0，则调用方必须在 IRQL <= APC_LEVEL 和非比特线程上下文中运行。 如果 超时 ！= NULL，超时 = 0，则调用方必须在 IRQL <= DISPATCH_LEVEL运行。
KeWaitForMutexObject 是转换为 KeWaitForSingleObject的宏，可以改用该宏。
为了获得更好的性能，请使用快速互斥体或受保护的互斥体。 有关详细信息，请参阅 互斥对象的替代项。
有关互斥对象的详细信息，请参阅 互斥体对象。