Struct TimerWheel 

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

A multi-level, no-cascade timer wheel.

Generic over:

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

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, level slot arrays) — moving the wheel moves the heap data with it.

Implementations

impl<T: 'static> TimerWheel<T>

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

Creates an unbounded timer wheel with default configuration.

For custom configuration, use WheelBuilder.

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

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

Creates a bounded timer wheel with default configuration.

For custom configuration, use WheelBuilder.

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

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

Schedules a timer and returns a handle for cancellation.

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

Panics

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

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

Schedules a fire-and-forget timer (no handle returned).

The timer will fire during poll and the value will be collected. Cannot be cancelled.

Panics

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

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

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

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

Returns Err(Full(value)) if the slab is at capacity. Use this when you need graceful error handling. For the common case where capacity exhaustion is fatal, use schedule.

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

Attempts to schedule a fire-and-forget timer.

Returns Err(Full(value)) if the slab is at capacity. Use this when you need graceful error handling. For the common case where capacity exhaustion is fatal, use schedule_forget.

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

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

Cancels a timer and returns its value.

• If the timer is still active: unlinks from the wheel, extracts value, frees the slab entry. Returns Some(T).
• If the timer already fired (zombie handle): frees the slab entry. Returns None.

Consumes the handle (no Drop runs).

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

Releases a timer handle without cancelling.

• If the timer is still active: converts to fire-and-forget (refs 2→1). Timer stays in the wheel and will fire normally during poll.
• If the timer already fired (zombie): frees the slab entry (refs 1→0).

Consumes the handle (no Drop runs).

pub fn reschedule( &mut self, handle: TimerHandle<T>, new_deadline: Instant, ) -> TimerHandle<T>

Reschedules an active timer to a new deadline.

Moves the entry from its current slot to the correct slot for new_deadline without extracting or reconstructing the value.

Panics

Panics if the timer has already fired (zombie handle). Only active timers (refs == 2) can be rescheduled.

Consumes and returns a new handle (same entry, new position).

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.

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.

Resumable: if the limit is hit, the next call continues where this one left off (as long as now hasn’t changed).

Returns the number of timers fired in this call.

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

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

Walks only active (non-empty) slots. O(active_slots) in the worst case, but typically very fast because most slots are empty.

pub fn len(&self) -> usize

Returns the number of timers currently in the wheel.

pub fn is_empty(&self) -> bool

Returns true if the wheel contains no timers.

Trait Implementations

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

fn drop(&mut self)

Executes the destructor for this type.

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