Struct rsevents::AutoResetEvent
source · [−]pub struct AutoResetEvent { /* private fields */ }
Expand description
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
sourceimpl AutoResetEvent
impl AutoResetEvent
sourcepub const fn new(state: EventState) -> AutoResetEvent
pub const fn new(state: EventState) -> AutoResetEvent
Create a new AutoResetEvent
that can be used to atomically signal one waiter at a time.
sourcepub fn set(&self)
pub fn set(&self)
Triggers the underlying RawEvent
, either releasing one suspended waiter or allowing one
future caller to exclusively obtain the event.
sourcepub fn reset(&self)
pub fn reset(&self)
Set the state of the internal event to EventState::Unset
, regardless of its current
status.
Trait Implementations
sourceimpl Awaitable<'_> for AutoResetEvent
impl Awaitable<'_> for AutoResetEvent
sourcefn try_wait(&self) -> Result<Self::T, Infallible>
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.
sourcefn try_wait_for(&self, limit: Duration) -> Result<(), TimeoutError>
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.
sourcefn try_wait0(&self) -> Result<(), TimeoutError>
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 Error = TimeoutError
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. Read more
sourcefn wait(&'a self) -> Self::T where
Self::Error: InfallibleUnboundedWait,
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. Read more
sourcefn wait_for(&'a self, limit: Duration) -> bool where
Self: VoidAwaitable,
Self::Error: InfallibleUnboundedWait,
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. Read more
sourcefn wait0(&'a self) -> bool where
Self: VoidAwaitable,
Self::Error: InfallibleUnboundedWait,
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. Read more
Auto Trait Implementations
impl RefUnwindSafe for AutoResetEvent
impl Send for AutoResetEvent
impl Sync for AutoResetEvent
impl Unpin for AutoResetEvent
impl UnwindSafe for AutoResetEvent
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more