Struct rsevents::AutoResetEvent

pub struct AutoResetEvent { /* fields omitted */ }

An AutoResetEvent is a gated event that is functionally equivalent to a "waitable boolean" and can be atomically waited upon and consumed to signal one and only one waiter at a time, thereby guaranteeing exclusive access to a critical section.

While an AutoResetEvent can be used to implement mutexes and condition variables, it is more appropriate for uses involving signalling between two or more threads. Unlike a ManualResetEvent, an AutoResetEvent's set state is selectively made visible to only one waiter at a time (including past waiters currently in a suspended/parked state). When AutoResetEvent::set() is called, at most one thread blocked in a call to Awaitable::wait() will be let through (hence the "gated" description). If a previously parked thread was awaked, then the event's state remains unset for all future callers, but if no threads were previously parked waiting for this event to be signalled then only the next thread to call AutoResetEvent::wait() on this instance will be let through without blocking.

Auto-reset events are thread-safe and may be wrapped in an Arc to easily share across threads.

Methods

impl AutoResetEvent

pub fn new(state: State) -> AutoResetEvent

Create a new AutoResetEvent that can be used to atomically signal one waiter at a time.

pub fn set(&self)

Triggers the underlying [RawEvent], either releasing one suspended waiter or allowing one future caller to exclusively obtain the event.

pub fn reset(&self)

Set the state of the internal event to State::Unset, regardless of its current status.

Trait Implementations

impl Awaitable for AutoResetEvent

fn wait(&self)

Check if the event has been signalled, and if not, block waiting for it to be set. When the event becomes available, its state is atomically set to State::Unset, allowing only one waiter through.

fn wait_for(&self, limit: Duration) -> bool

Check if the event has been signalled, and if not, block for limit waiting for it to be set. If and when the event becomes available, its state is atomically set to State::Unset, allowing only one waiter through.

Returns true if the event was originally set or if it was signalled within the specified duration, and false otherwise (if the timeout elapsed without the event becoming set).

fn wait0(&self) -> bool

Test if an event is available without blocking, returning false immediately if it is not set. This is not a peek() function: if the event's state was State::Set, it is atomically reset to State::Unset.

Note that this is additionally not the same as calling Awaitable::wait_for() with a Duration of zero, as the calling thread never yields.