KeWaitForSingleObject

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

KeWaitForSingleObject puts the current thread into an alertable or nonalertable wait state until the given dispatcher object is set to the Signaled state or (optionally) until the wait times out.

Parameters

Object: Points to an initialized dispatcher object (event, mutex, semaphore, thread, or timer) for which the caller supplies the storage.
WaitReason: Specifies the reason for the wait, which should be set to Executive by drivers or, if the driver is doing work on behalf of a user and is running in the context of a User thread, to UserRequest.
WaitMode: Specifies whether the caller waits in KernelMode or UserMode. Lowest-level and intermediate drivers should specify KernelMode. If the given Object is a mutex, the caller must specify KernelMode.
Alertable: Specifies a Boolean value that indicates whether the wait is alertable.
Timeout: Points to a time-out value that specifies the absolute or relative time at which the wait is to be completed (optional). A negative value specifies an interval relative to the current time. The value should be expressed in units of 100 nanoseconds. Absolute expiration times track any changes in the system time; relative expiration times are not affected by system time changes.

Return Value

KeWaitForSingleObject can return one of the following status values:

Value

Meaning

STATUS_SUCCESS

The dispatcher object specified by the Object parameter satisfied the wait.

STATUS_ALERTED

The wait was completed because of an alert to the thread.

STATUS_USER_APC

A user APC was delivered to the current thread before the specified Timeout interval expired.

STATUS_TIMEOUT

A time-out occurred before the object was set to Signaled. This value can be returned when an explicit time-out value of zero is specified and the specified set of wait conditions cannot be immediately met.

Comments

The current state of the specified Object is examined to determine whether the wait can be satisfied immediately. If so, the necessary side effects are performed on the object. Otherwise, the current thread is put in a waiting state and a new thread is selected for execution on the current processor.

The Alertable parameter specifies whether the thread can be alerted in the wait state. If the value of this parameter is TRUE and the thread is alerted for a mode that is equal to or more privileged than the given WaitMode, the thread’s wait will be satisfied with a completion status of STATUS_ALERTED.

If the WaitMode parameter is UserMode and the Alertable parameter is TRUE, the thread can also be awakened to deliver a user-mode APC. Kernel-mode APCs always cause the subject thread to be awakened if the wait IRQL is PASSIVE_LEVEL and no kernel APC is in progress.

If no Timeout is supplied, the calling thread will remain in a Wait state until the Object is signalled.

A Timeout of zero allows the testing of a set of wait conditions and for conditionally performing any side effects if the wait can be immediately satisfied, as in the acquisition of a mutex.

Callers of KeWaitForSingleObject must be running at IRQL <= DISPATCH_LEVEL. Usually, the caller must be running at IRQL PASSIVE_LEVEL and in a nonarbitrary thread context. A call while running at IRQL DISPATCH_LEVEL is valid if and only if the caller specifies a Timeout of zero. That is, a driver must not wait for a nonzero interval at IRQL DISPATCH_LEVEL.

Value	Meaning
STATUS_SUCCESS	The dispatcher object specified by the Object parameter satisfied the wait.
STATUS_ALERTED	The wait was completed because of an alert to the thread.
STATUS_USER_APC	A user APC was delivered to the current thread before the specified Timeout interval expired.
STATUS_TIMEOUT	A time-out occurred before the object was set to Signaled. This value can be returned when an explicit time-out value of zero is specified and the specified set of wait conditions cannot be immediately met.