Struct AutoResetEvent 

pub struct AutoResetEvent { /* private fields */ }

Available on crate feature event only.

A reusable signal that releases one waiter and resets automatically.

Each set assigns a signal to one registered wait, or stores one signal if no wait is queued. Repeated sets coalesce only while an unassigned signal is stored. A signal assigned to a wait belongs to that wait until it completes or is cancelled; subsequent sets can release other waits even before previously selected waits are polled again. An unassigned signal can be cleared with reset.

Waiting consumes a signal without returning it on completion. Unlike a ManualResetEvent, this event does not release all observers of a condition. Unlike a semaphore, it does not count unused signals or return a permit guard.

Usage

Use this event for a single worker that rechecks external state after a signal. Publish the state before calling set, and check the predicate in a loop. A signal arriving between the predicate check and the first poll is retained, so the worker does not miss it. A leftover signal can cause an extra predicate check without implying new work.

Multiple waits compete for signals. The simple check-then-wait loop is not a general multi-consumer queue protocol: several changes can coalesce before those consumers register their waits.

Synchronization

Memory operations sequenced before a set are visible after a wait or try_wait consumes its signal. This includes sets coalesced into a stored signal and signals passed on after cancellation.

The event carries no application state: callers must synchronize access to external predicates separately.

Examples

use asyncband::event::AutoResetEvent;

let event = AutoResetEvent::new();
event.set();
event.set();
event.wait().await;
assert!(!event.try_wait()); // The two sets coalesced into one signal.

Implementations

impl AutoResetEvent

pub const fn new() -> Self

Creates an unset event.

pub const fn with_state(is_set: bool) -> Self

Creates an event with the specified initial state.

If is_set is true, the event stores one signal for a future wait.

pub fn set(&self)

Signals one registered wait, or stores one signal if no wait is queued.

A stored signal is available to a future wait. Further sets coalesce while it remains unassigned. Creating a wait future does not register it; registration happens when it is first polled without a stored signal.

Panics

Panics if waking a selected task panics. Its signal remains assigned and can still be consumed by polling that wait or passed on by dropping it.

pub fn reset(&self)

Clears any stored, unassigned signal.

Signals already assigned to waits remain theirs. Cancelling such a wait can still transfer or restore its signal after this call. If no signal is stored, this has no effect.

pub fn is_set(&self) -> bool

Returns whether the event is currently set.

The event is set while it stores an unassigned signal. Signals already assigned to waits are not reflected in this state.

This is a snapshot only; it does not change the event or reserve a signal for a later wait. The state may change immediately after this call.

Examples

use asyncband::event::AutoResetEvent;

let event = AutoResetEvent::with_state(true);
assert!(event.is_set());
assert!(event.is_set());

pub fn try_wait(&self) -> bool

Attempts to wait without registering a waiter.

Returns true if a stored signal was consumed. This never takes a signal assigned to another wait. A false result is only a snapshot; use wait to wait for a future signal.

Examples

use asyncband::event::AutoResetEvent;

let event = AutoResetEvent::with_state(true);
assert!(event.try_wait());
assert!(!event.try_wait()); // A successful wait consumes the signal.

pub async fn wait(&self)

Waits for and consumes one signal.

The first poll consumes a stored signal immediately, or registers the wait. Merely creating this future neither reserves a signal nor registers the wait. Signals assigned to other waits cannot be consumed by this wait.

Cancel safety

Dropping this future before it returns Ready removes its registration. If a signal was assigned to it, that signal is passed to another registered wait or stored for a future wait, coalescing with any signal already stored. Dropping a completed wait does not return its consumed signal.

pub async fn wait_owned(self: Arc<Self>)

Waits without borrowing the event.

The future owns the Arc, making it suitable for spawned tasks. Its waiting and cancellation semantics match wait.

Examples

use std::sync::Arc;

use asyncband::event::AutoResetEvent;

let event = Arc::new(AutoResetEvent::new());
let waiter = tokio::spawn(event.clone().wait_owned());
event.set();
waiter.await.unwrap();

Trait Implementations

impl Debug for AutoResetEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AutoResetEvent

fn default() -> Self

Returns the “default value” for a type.