KeReleaseSemaphore

KeReleaseSemaphore

LONG
KeReleaseSemaphore(
IN PKSEMAPHORE Semaphore,
IN KPRIORITY Increment,
IN LONG Adjustment,
IN BOOLEAN Wait
);

KeReleaseSemaphore releases a given semaphore object. This routine supplies a runtime priority boost for waiting threads. If this call sets the semaphore to the Signaled state, the semaphore count is augmented by the given value. The caller can also specify whether it will call one of the KeWaitXxx routines as soon as KeReleaseSemaphore returns control.

Parameters

Semaphore

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

Increment

Specifies the priority increment to be applied if releasing the semaphore causes a wait to be satisfied.

Adjustment

Specifies a value to be added to the current semaphore count. This value must be positive.

Wait

Specifies whether the call to KeReleaseSemaphore is to be followed immediately by a call to one of the KeWaitXxx.

Return Value

If the return value is zero, the previous state of the semaphore object is Not-Signaled.

Comments

Releasing a semaphore object causes the semaphore count to be augmented by the value of the Adjustment parameter. If the resulting value is greater than the limit of the semaphore object, the count is not adjusted and an exception, STATUS_SEMAPHORE_COUNT_EXCEEDED, is raised.

Augmenting the semaphore object count causes the semaphore to attain a state of Signaled, and an attempt is made to satisfy as many waits as possible on the semaphore object.

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 KeReleaseSemaphore must be followed immediately by a call to one of the KeWaitXxx.

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

Callers of KeReleaseSemaphore must be running at IRQL <= DISPATCH_LEVEL provided that Wait is set to FALSE. Otherwise, the caller must be running at IRQL PASSIVE_LEVEL.