KeWaitForMutexObject

KeWaitForMutexObject

NTSTATUS
KeWaitForMutexObject(
IN PKMUTEX Mutex,
IN KWAIT_REASON WaitReason,
IN KPROCESSOR_MODE WaitMode,
IN BOOLEAN Alertable,
IN PLARGE_INTEGER Timeout /* optional */
);

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

Parameters

Mutex

Points to an initialized mutex object for which the caller supplies the storage.

WaitReason

Specifies the reason for the wait, which should be set to Executive, 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

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

KeWaitForMutexObject can return one of the following status values:

Value	Meaning
STATUS_SUCCESS	The dispatcher object specified by the Mutex 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 mutex 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

KeWaitForMutexObject is a macro which converts to KeWaitForSingleObject which can be used instead.

For better performance, use the Ex..FastMutex routines instead of the Ke..Mutex. However, a fast mutex cannot be acquired recursively, as a kernel mutex can.

The current state of the given mutex object is examined to determine whether the wait can be satisfied immediately. If so, the necessary side effects are performed on the mutex. 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 Mutex 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, such as acquiring the Mutex.

Callers of KeWaitForMutexObject 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.