Struct rsevents::ManualResetEvent

pub struct ManualResetEvent { /* private fields */ }

A ManualResetEvent is an event type best understood as an “awaitable boolean” that efficiently synchronizes thread access to a shared state, allowing one or more threads to wait for a signal from one or more other threads, where the signal could have either occurred in the past or could come at any time in the future.

Unlike an AutoResetEvent which atomically allows one and only one waiter through each time the underlying RawEvent is set, a ManualResetEvent unparks all past waiters and allows all future waiters calling Awaitable::wait() to continue without blocking (until ManualResetEvent::reset() is called).

A ManualResetEvent is rarely appropriate for general purpose thread synchronization (à la condition variables and mutexes), where exclusive access to a protected critical section is usually desired, as if multiple threads are suspended/parked waiting for the event to be signalled and then ManualResetEvent::set() is called, all of the suspended threads will be unparked and will resume. However, a ManualResetEvent shines when it comes to setting persistent state indicators, such as a globally-shared abort flag.

Manual-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 ManualResetEvent

pub const fn new(state: EventState) -> ManualResetEvent

Create a new ManualResetEvent with the initial EventState set to state.

pub fn set(&self)

Puts the ManualResetEvent into a set state, releasing all suspended waiters (if any) and leaving the event set for future callers to ManualResetEvent::wait() and co.

pub fn reset(&self)

Set the state of the ManualResetEvent to EventState::Unset, regardless of its current state. This will cause future calls to ManualResetEvent::wait() to block until the event is set (via ManualResetEvent::set()).

Trait Implementations

impl Awaitable<'_> for ManualResetEvent

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

Check if the underlying event is in a set state or wait for its state to become EventState::Set. In contrast with AutoResetEvent::try_wait(), the event’s state is not affected by this operation, i.e. it remains set for future callers even after this function call returns (until a call to ManualResetEvent::reset() is made).

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

Check if the underlying event is in a set state (and return immediately) or wait for it to become set, up to the limit specified by the Duration parameter.

Returns Ok(()) if the event was initially set or if it became set within the timeout specified, otherwise returns Err(TimeoutError) if the timeout elapsed with thet event becoming available.

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

Test if an event is available without blocking, returning Err(TimeoutErr) immediately if it is not set.

Note that this is not the same as calling ManualResetEvent::try_wait_for() with a Duration of zero, as the calling thread never 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.