Kernel events - microsoft/wil GitHub Wiki

wil::kernel_event_t is a family of classes defined in wil/resource.h as part of the RAII resource wrappers library. It is very similar to wil::unique_event (see Event handles) but for use in kernel-mode code. It wraps a KEVENT. This is a very lightweight class that exists primarily for the benefit of automatic initialization on construction.

The two variants of this class are:

  • wil::kernel_event_auto_reset, also known as wil::kernel_event. The event becomes reset when a waiting thread is released. This is a KEVENT of type SynchronizationEvent.
  • wil::kernel_event_manual_reset. The event remains set until explicitly reset. This is a KEVENT of type NotificationEvent.

Sample usage:

// Default state is not signaled.
wil::kernel_event finished;

// Time is specified in 100ns units, like in KeWaitForSingleObject.
if (!finished.wait(-1ll * 1 * 1000 * 1000 * 1000 / 100))
{
    finished.set();
}

// Wait indefinitely.
finished.wait();

Class summary:

Constructors

  • kernel_event_t(bool isSignaled = false): Construct an event with initial state as specified.

Methods

  • PRKEVENT get(): Obtain a pointer to the underlying KEVENT.
  • void set(KPRIORITY increment = IO_NO_INCREMENT): Sets the event by calling KeSetEvent with the specified priority increment.
  • void clear(): Clears the event by calling KeClearEvent.
  • bool is_signaled(): Checks whether the event is signaled without changing its state.
  • void wait(): Wait indefinitely for the event to be set.
  • bool wait(LONGLONG waitTime): Wait for the event to be set, up to a relative or absolute point in time. Returns true if the wait succeeded, or false if the wait timed out. The time is specified in a manner similar to that in KeWaitForSingleObject.