Struct rsevents::ManualResetEvent

pub struct ManualResetEvent { /* fields omitted */ }

A ManualResetEvent is an event type best understood as a "waitable 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 to easily share across threads.

Methods

impl ManualResetEvent

pub fn new(state: State) -> ManualResetEvent

Create a new ManualResetEvent.

pub fn set(&self)

Puts the underlying [RawEvent] into a set state, releasing all suspended waiters (if any) and leaving the event set for future callers.

pub fn reset(&self)

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

Trait Implementations

impl Awaitable for ManualResetEvent

fn wait(&self)

Check if the underlying event is in a set state or wait for its state to become State::Set. The event's state is not affected by this operation, i.e. it remains set for future callers even after this function call returns.

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

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 true if the event was initially set or if it became set within the timelimit specified. Otherise returns false if the timeout elapsed without the event becoming available.

fn wait0(&self) -> bool

Test if an event is available without blocking, returning false immediately if it is not set.

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