Skip to main content

TimeoutQueue

Struct TimeoutQueue 

Source
pub struct TimeoutQueue<T: 'static, S: SlabStore<Item = WheelEntry<T>> = Slab<WheelEntry<T>>> { /* private fields */ }
Expand description

A fixed-duration timeout queue with O(fired) poll and O(1) exact next-deadline.

Generic over:

  • T — the user payload stored with each timer.
  • S — the slab storage backend. Defaults to unbounded::Slab.

Every timer uses the same duration, fixed at construction. See the module docs for the invariant this exploits.

§No reschedule

Rescheduling later is push-to-tail and stays ordered, but rescheduling earlier would break the sort — and the two are indistinguishable in a single API. So no reschedule is offered: callers cancel and re-schedule, which is the same two operations without the ordering hazard. (This mirrors the wheel’s reschedule, deliberately omitted here.)

§Thread Safety

Send but !Sync. Can be moved to a thread at setup but must not be shared. All internal raw pointers point into owned allocations (slab chunks) — moving the list moves the heap data with it.

Implementations§

Source§

impl<T: 'static> TimeoutQueue<T>

Source

pub fn unbounded(timeout: Duration, chunk_capacity: usize, now: Instant) -> Self

Creates an unbounded timeout queue with the default 1ms tick.

Every timer fires timeout after the now passed to schedule. The now here fixes the reference epoch — pass one monotone clock source (e.g. Instant::now()) here and to every schedule/poll. For a custom tick duration, use TimeoutQueueBuilder.

§Panics

Panics if timeout is zero. Use [TimeoutQueueBuilder::build] to handle a runtime-sourced timeout without panicking.

Source§

impl<T: 'static> TimeoutQueue<T, Slab<WheelEntry<T>>>

Source

pub fn bounded(timeout: Duration, capacity: usize, now: Instant) -> Self

Creates a bounded timeout queue with the default 1ms tick.

Every timer fires timeout after the now passed to schedule. The now here fixes the reference epoch — pass one monotone clock source (e.g. Instant::now()) here and to every schedule/poll. For a custom tick duration, use TimeoutQueueBuilder.

§Panics

Panics if timeout is zero. Use [TimeoutQueueBuilder::build] to handle a runtime-sourced timeout without panicking.

Source§

impl<T: 'static, S: SlabStore<Item = WheelEntry<T>>> TimeoutQueue<T, S>

Source

pub fn schedule(&mut self, now: Instant, value: T) -> TimerHandle<T>

Schedules a timer for now + timeout and returns a handle for cancellation.

The handle must be consumed via cancel or free. Dropping it is a programming error.

now must be monotonically non-decreasing across calls (a plain Instant::now() at each call site satisfies this). A now that goes backwards trips a debug_assert! in debug builds.

§Panics

Panics if the backing slab is at capacity (bounded slabs only). This is a capacity planning error — size the list for peak load.

Source

pub fn schedule_forget(&mut self, now: Instant, value: T)

Schedules a fire-and-forget timer for now + timeout (no handle returned).

The timer fires during poll and its value is collected. It cannot be cancelled. See schedule for the now monotonicity requirement.

§Panics

Panics if the backing slab is at capacity (bounded slabs only).

Source§

impl<T: 'static, S: BoundedStore<Item = WheelEntry<T>>> TimeoutQueue<T, S>

Source

pub fn try_schedule( &mut self, now: Instant, value: T, ) -> Result<TimerHandle<T>, Full<T>>

Attempts to schedule a timer, returning a handle on success.

Returns Err(Full(value)) — with the caller’s T recovered, not the internal WheelEntry — if the slab is at capacity. Use this when capacity exhaustion should be handled gracefully; otherwise use schedule.

Source

pub fn try_schedule_forget( &mut self, now: Instant, value: T, ) -> Result<(), Full<T>>

Attempts to schedule a fire-and-forget timer.

Returns Err(Full(value)) — with the caller’s T recovered — if the slab is at capacity. Otherwise use schedule_forget.

Source§

impl<T: 'static, S: SlabStore<Item = WheelEntry<T>>> TimeoutQueue<T, S>

Source

pub fn cancel(&mut self, handle: TimerHandle<T>) -> Option<T>

Cancels a timer and returns its value.

  • Still active (refs == 2): unlinks from the list, extracts the value, frees the slab entry. Returns Some(T). O(1) — a mid-list unlink, no residency, no tombstone.
  • Already fired (zombie handle, refs == 1): frees the slab entry. Returns None.

Consumes the handle (no Drop runs).

Source

pub fn free(&mut self, handle: TimerHandle<T>)

Releases a timer handle without cancelling.

  • Still active: converts to fire-and-forget (refs 2 -> 1). The timer stays in the list and fires normally during poll.
  • Already fired (zombie): frees the slab entry (refs 1 -> 0).

Consumes the handle (no Drop runs).

Source

pub fn poll(&mut self, now: Instant, buf: &mut Vec<T>) -> usize

Fires all expired timers, collecting their values into buf.

Returns the number of timers fired. O(fired): the list is sorted, so this walks from the head and stops at the first not-due entry.

Source

pub fn poll_with_limit( &mut self, now: Instant, limit: usize, buf: &mut Vec<T>, ) -> usize

Fires expired timers up to limit, collecting values into buf.

Returns the number fired in this call. Truncation is resumable: this stops at a head that is either not-due or beyond limit, and the next call picks up at exactly that head. No bookmark is needed — the sorted list is the cursor. (The wheel needs a resumption argument because it re-derives its scan position each call; here there is nothing to re-derive.)

Source

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

Returns the Instant of the next timer that will fire, or None if empty.

O(1), exact: the sorted list’s head is the minimum deadline. No cache.

Source

pub fn len(&self) -> usize

Returns the number of timers currently in the list.

Source

pub fn is_empty(&self) -> bool

Returns true if the list contains no timers.

Trait Implementations§

Source§

impl<T: 'static, S: SlabStore<Item = WheelEntry<T>>> Drop for TimeoutQueue<T, S>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more
Source§

impl<T: Send + 'static, S: SlabStore<Item = WheelEntry<T>>> Send for TimeoutQueue<T, S>

Auto Trait Implementations§

§

impl<T, S = Slab<WheelEntry<T>>> !Freeze for TimeoutQueue<T, S>

§

impl<T, S = Slab<WheelEntry<T>>> !RefUnwindSafe for TimeoutQueue<T, S>

§

impl<T, S = Slab<WheelEntry<T>>> !Sync for TimeoutQueue<T, S>

§

impl<T, S = Slab<WheelEntry<T>>> !UnwindSafe for TimeoutQueue<T, S>

§

impl<T, S> Unpin for TimeoutQueue<T, S>
where WheelSlot<T>: Unpin, S: Unpin,

§

impl<T, S> UnsafeUnpin for TimeoutQueue<T, S>
where WheelSlot<T>: UnsafeUnpin, S: UnsafeUnpin,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.