KeSetEvent function (wdm.h)

Article
04/18/2022

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.

Syntax

LONG KeSetEvent(
  [in, out] PRKEVENT  Event,
  [in]      KPRIORITY Increment,
  [in]      BOOLEAN   Wait
);

Parameters

[in, out] Event

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

[in] Increment

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

[in] Wait

Specifies whether the call to KeSetEvent is to be followed immediately by a call to one of the KeWaitXxx routines. If TRUE, the KeSetEvent call must be followed by a call to KeWaitForMultipleObjects, KeWaitForMutexObject, or KeWaitForSingleObject. For more information, see the following Remarks section.

Return value

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

Remarks

Calling KeSetEvent causes the event to attain a signaled state. If the event is a notification event, the system attempts to satisfy as many waits as possible on the event object. The event remains signaled until a call to KeClearEvent or KeResetEvent clears it. If the event is a synchronization event, one wait is satisfied before the system automatically clears the event.

The KeSetEvent routine might temporarily raise the IRQL. If the Wait parameter is FALSE, the routine, before it returns, restores the IRQL to the original value that it had at the start of the call.

If Wait = TRUE, the routine returns without lowering the IRQL. In this case, the KeSetEvent call must be immediately followed by a KeWaitXxx call. By setting Wait = TRUE, the caller can prevent an unnecessary context switch from occurring between the KeSetEvent call and the KeWaitXxx call. The KeWaitXxx routine, before it returns, restores the IRQL to its original value at the start of the KeSetEvent call. Although the IRQL disables context switches between the two calls, these calls cannot reliably be used as the start and end of an atomic operation. For example, between these two calls, a thread that is running at the same time on another processor might change the state of the event object or of the target of the wait.

A pageable thread or pageable driver routine that runs at IRQL = PASSIVE_LEVEL should never call KeSetEvent with the Wait parameter set to TRUE. Such a call causes a fatal page fault if the caller happens to be paged out between the calls to KeSetEvent and KeWaitXxx.

For more information about event objects, see Event Objects.

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

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 2000.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	See Remarks section.
DDI compliance rules	CompletionEventChecking(wdm), DoubleKeSetEvent(storport), HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoBuildDeviceIoControlSetEvent(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IrqlKeSetEvent(wdm), SignalEventInCompletion(wdm)