Export (0) Print
Expand All
Expand Minimize

KePulseEvent routine

The KePulseEvent routine atomically sets an event object to a signaled state, attempts to satisfy as many waits as possible, and then resets the event object to a not-signaled state.

Syntax


LONG KePulseEvent(
  _Inout_  PRKEVENT Event,
  _In_     KPRIORITY Increment,
  _In_     BOOLEAN Wait
);

Parameters

Event [in, out]

A pointer to a dispatcher object of type KEVENT.

Increment [in]

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

Wait [in]

Specifies a Boolean value that signifies whether the call to KePulseEvent will be immediately followed by a call to one of the KeWaitXxx routines. If TRUE, the KePulseEvent call is immediately followed by a call to KeWaitForMultipleObjects, KeWaitForMutexObject, or KeWaitForSingleObject. For more information, see the following Remarks section.

Return value

The previous signal state of the event object.

Remarks

For more information about event objects, see Event Objects.

The KePulseEvent 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 KePulseEvent 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 KePulseEvent call and the KeWaitXxx call. The KeWaitXxx routine, before it returns, restores the IRQL to its original value at the start of the KePulseEvent 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.

If the caller is executing at IRQL = DISPATCH_LEVEL or in an arbitrary thread context, the Timeout parameter to KeWaitXxx must be zero.

Warning   If a thread waiting for Event is currently running a kernel APC, then, when KePulseEvent is called, this thread's wait is not satisfied. After the kernel APC completes, the thread remains in the wait state.

Requirements

Version

Available starting with Windows 2000.

Header

Ntddk.h (include Ntddk.h)

Library

Ntoskrnl.lib

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

IrqlKeDispatchLte, HwStorPortProhibitedDDIs

See also

KeInitializeEvent
KeReadStateEvent
KeResetEvent
KeSetEvent
KeWaitForMultipleObjects
KeWaitForMutexObject
KeWaitForSingleObject

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft