Slim events - microsoft/wil GitHub Wiki

wil::slim_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 without requiring a kernel object.

The two variants of this class are:

  • wil::slim_event_auto_reset, also known as wil::slim_event. The event becomes reset when a waiting thread is released.
  • wil::slim_event_manual_reset. The event remains set until explicitly reset.

Some key differences from wil::unique_event include:

  • There is no create() function, as initialization occurs in the constructor and can't fail.
  • The object is not movable (or copyable).
  • For auto-reset events, the is_signaled() function doesn't reset the event. (Use ResetEvent() instead.)
  • The ResetEvent() function returns the previous state of the event.

The wil::slim_event_t has the same race conditions as kernel events. For example, signaling a thread does not guarantee that the thread has been woken before the SetEvent() call returns.

Sample usage:

wil::slim_event finished;
std::thread doStuff([&finished] () {
    Sleep(10);
    finished.SetEvent();
});
finished.wait(); // waits until finished.SetEvent() is called

std::shared_ptr<wil::slim_event> CreateSharedEvent(bool startSignaled)
{
    return std::make_shared<wil::slim_event>(startSignaled);
}

Class summary:

Constructors

  • slim_event_t(): Construct a slim event, initially unsignaled.
  • slim_event_t(bool isSignaled): Construct a slim event with initial state as specified.

Methods

  • bool ResetEvent(): Resets the event and returns the previous state.
  • void SetEvent(): Sets the event and wakes one (if auto-reset) or all (if manual-reset) waiters.
  • bool is_signaled(): Checks whether the event is signaled without changing its state.
  • bool wait(): Wait indefinitely for the event to be set. Always returns true.
  • bool wait(DWORD timeoutMilliseconds): Wait for the event to be set, up to a timeout. Returns true if the wait succeeded, or false if the wait timed out.