Struct WakerSet 

pub struct WakerSet { /* private fields */ }

Set of wakers to be awakened when a certain event occurs

A WakerSet stores wakers that can later be awakened. It is used in the virtual system to manage wakers for events such as file readiness and signal delivery.

Wakers are stored as Weak<Cell<Option<Waker>>>. The asynchronous task that wants to be awakened creates a Cell<Option<Waker>> to hold its waker, and keeps a Rc to it until it is awakened as expected or it wants to cancel the wake-up. If the strong reference is dropped and the cell is deallocated before the waker is awakened, the WakerSet will not attempt to wake it, as the Weak reference will fail to upgrade. This design allows for automatic cleanup of wakers that are no longer valid without requiring explicit removal from the set.

The cell of the optional waker allows taking the waker out of the cell when waking, which is necessary to call Waker::wake without the need to clone the waker. After waking, the cell is set to None to indicate that the waker has been consumed and should not be woken again. This design also allows multiple sets for different events to share the same waker cell, as waking from one set will consume the waker and prevent it from being woken again from other sets, which is suitable when a task is waiting for multiple events and should be awakened when any of them occurs.

Wakers are considered dead when their weak reference cannot be upgraded or their cell contains None. Dead wakers are not awakened and may be automatically removed from the set as a side effect of other set operations.

A WakerSet internally uses a HashSet to store wakers. Wakers are compared by their pointer addresses, so adding the same waker multiple times will not create duplicates in the set.

Implementations

impl WakerSet

pub fn new() -> Self

Creates a new empty WakerSet.

pub fn capacity(&self) -> usize

Returns the capacity of the set.

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more wakers to be inserted without reallocating.

After calling this method, the capacity will be greater than or equal to the current item count plus additional. Does nothing if the capacity is already sufficient.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the set as much as possible.

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of the set to the specified minimum.

After this operation, the capacity will be at least min_capacity, but the set may have more capacity than that.

pub fn len(&self) -> usize

Returns the number of wakers in the set.

Wakers may become dead over time, so the actual number of valid wakers may be less than this count.

pub fn is_empty(&self) -> bool

Returns true if the set contains no wakers.

Wakers may become dead over time, so there may be no valid wakers even if this method returns false.

pub fn insert(&mut self, waker_cell: Weak<Cell<Option<Waker>>>) -> bool

Inserts a waker into the set.

Returns true if the waker was not already present in the set, and false if it was already present, in which case the set is not modified and the passed weak reference is dropped.

The amortized time complexity of this method is O(1). If the set is full, it will first clean up dead wakers and possibly reallocate to optimize the capacity for future insertions, which will cost O(n) time.

pub fn wake_all(&mut self)

Wakes all wakers in the set and clears the set.

If a waker has been consumed or its strong reference has been dropped, it is not awakened and simply removed from the set.

pub fn clear(&mut self)

Clears the set without waking any wakers.

Trait Implementations

impl Clone for WakerSet

fn clone(&self) -> WakerSet

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WakerSet

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

Formats the value using the given formatter.

impl Default for WakerSet

fn default() -> WakerSet

Returns the “default value” for a type.

impl FromIterator<Weak<Cell<Option<Waker>>>> for WakerSet

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = Weak<Cell<Option<Waker>>>>,

Creates a value from an iterator.

impl PartialEq for WakerSet

fn eq(&self, other: &WakerSet) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for WakerSet

impl StructuralPartialEq for WakerSet