KeSetEvent

LONG
    KeSetEvent(
        IN PKEVENT  Event,
        IN KPRIORITY  Increment,
        IN BOOLEAN  Wait
        );

KeSetEvent sets the state of an event object to Signaled if the event was not already signaled, and returns the previous state of the event object.

Parameters

Event

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

Increment

Specifies the priority increment to be applied if setting the event causes a wait to be satisfied.

Wait

Specifies whether the call to KeSetEvent is to be followed immediately by a call to a KeWaitXxx.

Return Value

If the previous state of the event object was Signaled, a nonzero value is returned.

Comments

Calling KeSetEvent causes the event to attain a Signaled state, and therefore, an attempt is made to satisfy as many waits as possible on the event object.

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

This allows the caller to set an event and 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 an event object.

If Wait is set to FALSE, the caller can be running at IRQL <= DISPATCH_LEVEL. Otherwise, callers of KeSetEvent must be running at IRQL PASSIVE_LEVEL and in a nonarbitrary thread context.

See Also

KeClearEvent, KeInitializeEvent, KeReadStateEvent, KeResetEvent, KeWaitForMultipleObjects, KeWaitForSingleObject