KeReleaseMutex

KeReleaseMutex

LONG
KeReleaseMutex(
IN PKMUTEX Mutex,
IN BOOLEAN Wait
);

KeReleaseMutex releases a given mutex object, specifying whether the caller is to call one of KeWaitXxx as soon as KeReleaseMutex returns control.

Parameters

Mutex

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

Wait

Specifies whether or not the call to KeReleaseMutex is to be immediately followed by a call to one of KeWaitXxx.

Return Value

If the return value is zero, the mutex object was released and attained a state of Signaled.

Comments

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.

If the mutex object attains a Signaled state, an attempt is made to satisfy a wait for the mutex object.

A mutex object can only be released by the thread currently holding the mutex. If an attempt is made to release a mutex not held by the thread, a bug check occurs. An attempt to release a mutex object whose current state is Signaled also causes a bug check to occur.

When a mutex object attains a Signaled state, it is removed from the list of mutexes held by that thread. If the thread's owned mutex list does not contain any more entries, the thread's original priority is restored.

If the value of the Wait parameter is TRUE, the return to the caller is executed without lowering IRQL or releasing the dispatcher database spin lock. Therefore, the call to KeReleaseMutex must be followed immediately by a call to one of KeWaitXxx.

This allows the caller to release a mutex and wait as one atomic operation, preventing a possibly superfluous context switch. However, a caller cannot wait at raised IRQL nor in an arbitrary thread context for a nonzero interval on a mutex object.

If a mutex is acquired recursively, the holding thread must call KeReleaseMutex as many times as it acquired the mutex to set it to the Signaled state.

Callers of KeReleaseMutex must be running at IRQL PASSIVE_LEVEL.