KeSetEvent

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

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

Parameters

Event

Pointer 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 one of the KeWaitXxx routines.

Return Value

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

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

Calling KeSetEvent causes the event to attain a signaled state. If the event is a notification event, the system attempts satisfy as many waits as possible on the event object before clearing the event. If the event is a synchronization event, one wait is satisfied before the event is cleared.

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 routines.

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