Struct rsevents::AutoResetEvent

pub struct AutoResetEvent { /* private fields */ }

An AutoResetEvent is a synchronization primitive that is functionally equivalent to an “awaitable boolean” and can be atomically waited upon and consumed to signal one and only one waiter at a time, thereby guaranteeing exclusive signalling. This is not unlike a multi-producer, multi-consumer non-broadcast Channel<()> with a buffer size of 1, except much more efficient and lightweight.

AutoResetEvent can be used to implement other synchronization objects such as mutexes and condition variables, but it is most 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 both past waiters currently in a suspended/parked state and future waiters that haven’t yet made a call to Awaitable::wait() or similar).

When AutoResetEvent::set() is called, at most one thread blocked in a call to Awaitable::wait() will be let through: if a previously parked thread was awakened, then the event’s state remains unset for all other past/future callers (until another call to AutoResetEvent::set()), but if no threads were previously parked waiting for this event to be signalled then only the next thread to call AutoResetEvent::wait() against this instance will be let through without blocking. Regardless of whether or not there are any threads currently waiting, the call to set() always returns immediately (i.e. it does not block until another thread attempts to obtain the event).

Auto-reset events are thread-safe and may be wrapped in an Arc or declared as a static global to easily share access across threads.

Implementations

impl AutoResetEvent

pub const fn new(state: EventState) -> 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 EventState::Unset, regardless of its current status.

Trait Implementations

impl Awaitable<'_> for AutoResetEvent

fn try_wait(&self) -> Result<Self::T, Infallible>

Check if the event has been signalled, and if not, block waiting for it to be set. When the event becomes available to this thread, its state is atomically set to EventState::Unset, allowing only this one waiter through until another call to AutoResetEvent::set() is made.

fn try_wait_for(&self, limit: Duration) -> Result<(), TimeoutError>

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 EventState::Unset before this method returns, allowing only this one waiter through.

fn try_wait0(&self) -> Result<(), TimeoutError>

“Wait” on the AutoResetEvent event without blocking, immediately returning Ok if the event was signalled for this thread and Err(TimeoutError) if it wasn’t set. This is not a peek() function: if the event’s state was EventState::Set, it is atomically reset to EventState::Unset, locking out all other waiters.

Note that this is similar but not identical to calling AutoResetEvent::try_wait_for() with a Duration of zero, as the calling thread never blocks or yields.

type T = ()

The type yielded by the Awaitable type on a successful wait

type Error = TimeoutError

The type yielded by the Awaitable type in case of an error, also specifying whether or not an unbounded Awaitable::wait() returns any error at all.

fn wait(&'a self) -> Self::T where
    Self::Error: InfallibleUnboundedWait, 

Blocks until the Awaitable type and its associated type T become available. Like try_wait() but bypasses error handling.

fn wait_for(&'a self, limit: Duration) -> bool where
    Self: VoidAwaitable,
    Self::Error: InfallibleUnboundedWait, 

Attempts a bounded wait on the the Awaitable type. Like try_wait_for() but returns true if the Awaitable was originally available or if it became so within the specified duration and false otherwise.

fn wait0(&'a self) -> bool where
    Self: VoidAwaitable,
    Self::Error: InfallibleUnboundedWait, 

Attempts to obtain the Awaitable in a potentially lock-free, wait-free manner, returning a timeout error if it’s currently unavailable. Like try_wait0() but returns true if the Awaitable was available and obtained or false otherwise.