Struct ScheduledWakerQueue 

pub struct ScheduledWakerQueue { /* private fields */ }

Priority queue of scheduled wakers to wake up processes at specific times

This struct represents a priority queue of scheduled wakers, where each waker is associated with a specific time at which a process should be woken up.

The queue is effectively an extension of WakerSet ordered by wake time, and is (currently) implemented as a pair of a BTreeSet and a HashMap to allow efficient insertion and deduplication of wakers. See the documentation of WakerSet for more details on the data structure of wakers and the rationale behind it.

Like WakerSet, wakers in this queue are compared by their pointer addresses, and dead wakers in the queue may be automatically removed as a side effect of other operations.

Implementations

impl ScheduledWakerQueue

pub fn new() -> Self

Creates a new empty ScheduledWakerQueue.

pub fn len(&self) -> usize

Returns the number of scheduled wakers in the queue.

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

Checks if the queue is empty.

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

pub fn clear(&mut self)

Clears all scheduled wakers from the queue.

pub fn push( &mut self, wake_time: Instant, waker: Weak<Cell<Option<Waker>>>, ) -> bool

Pushes a new scheduled waker into the queue.

This method adds a new scheduled waker to the priority queue so that the associated process can be woken up at the specified time.

Returns true if the waker was successfully added to the queue, or false if it was already present or dead, in which case the passed weak reference is dropped.

The amortized time complexity of this method is O(log(n)). If the queue is full, it will first clean up dead wakers and possibly reallocate to optimize the capacity for future insertions, which will cost O(n log(n)) time. Because of this cleanup, the number of wakers in the queue may decrease after calling this method, regardless of whether the new waker was added or not.

pub fn next_wake_time(&self) -> Option<Instant>

Returns the next scheduled wake time, if any.

This method peeks at the priority queue to find the scheduled waker with the earliest wake time. If the queue is not empty, it returns the wake time of that waker; otherwise, it returns None.

If you have a mutable reference to the queue, you can use trim_to_next_wake_time instead of this method to remove dead wakers as the queue is traversed to find the next wake time.

pub fn trim_to_next_wake_time(&mut self) -> Option<Instant>

Trims dead wakers to find the next wake time.

This method removes dead wakers from the beginning of the priority queue until it finds a live waker or the queue becomes empty. The return value is the wake time of the first live waker in the queue after trimming, or None if the queue is empty.

This method is solely for optimization purposes and does not affect the correctness of the queue. Using this method instead of next_wake_time can help avoid unnecessary processing of dead wakers, particularly when next_wake_time is followed by wake that will remove dead wakers anyway.

The push method will also call this method to clean up dead wakers before inserting a new waker, so you don’t need to call this method manually in most cases.

pub fn wake(&mut self, now: Instant)

Wakes up processes whose scheduled wake time has been reached.

This method checks the priority queue for any scheduled wakers whose wake time is less than or equal to the current time (now). For each such waker, it takes the waker from the Cell and calls wake() on it to wake up the associated process. After waking up the process, the item is removed from the queue.

Trait Implementations

impl Clone for ScheduledWakerQueue

fn clone(&self) -> ScheduledWakerQueue

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ScheduledWakerQueue

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

Formats the value using the given formatter.

impl Default for ScheduledWakerQueue

fn default() -> ScheduledWakerQueue

Returns the “default value” for a type.