Struct TimerWheel 

pub struct TimerWheel<T> { /* private fields */ }

High-performance hierarchical timing wheel

Uses a two-level hierarchy to efficiently handle timers across a wide time range:

• L0 (Fast wheel): Handles near-term timers (0 to ~1 second)
  • Fine-grained resolution for accurate short-term scheduling
  • Polled frequently for expired timers
• L1 (Medium wheel): Handles long-term timers (~1 second to ~18 minutes)
  • Coarser resolution to reduce memory overhead
  • Timers cascade down to L0 as their deadline approaches

The hierarchy allows O(1) scheduling and cancellation while supporting a wide range of timer durations without excessive memory usage.

Implementations

impl<T> TimerWheel<T>

pub fn new( tick_resolution: Duration, ticks_per_wheel: usize, worker_id: u32, ) -> Self

Create new hierarchical timer wheel

Arguments

• tick_resolution - L0 tick duration (must be power of 2 nanoseconds, typically 1.05ms)
• ticks_per_wheel - Number of spokes per wheel (must be power of 2, typically 1024)
• worker_id - Worker ID that owns this timer wheel

Timer Deadlines

All timer deadlines are specified as nanoseconds elapsed since wheel creation.

pub fn with_allocation( tick_resolution: Duration, ticks_per_wheel: usize, initial_tick_allocation: usize, worker_id: u32, ) -> Self

Create hierarchical timer wheel with custom initial allocation per tick

Arguments

• tick_resolution - L0 tick duration (must be power of 2 nanoseconds)
• ticks_per_wheel - Number of spokes per wheel (must be power of 2)
• initial_tick_allocation - Initial slots per tick (must be power of 2)
• worker_id - Worker ID that owns this timer wheel

Design Notes

The L1 tick resolution equals one full L0 rotation, creating a natural cascading relationship: when an L1 tick expires, all its timers are within L0’s coverage range and can be cascaded down.

pub fn schedule_timer( &mut self, deadline_ns: u64, data: T, ) -> Result<u64, TimerWheelError>

Schedule a timer for an absolute deadline

The deadline is specified as nanoseconds since wheel creation. The timer is automatically placed in the appropriate wheel (L0 for near-term, L1 for long-term) based on the deadline value.

Arguments

• deadline_ns - Absolute deadline in nanoseconds (must be > 0 and in the future)
• data - User data to associate with this timer

Returns

Returns a timer ID that can be used to cancel the timer, or an error if the deadline is invalid or capacity is exceeded.

pub fn cancel_timer( &mut self, timer_id: u64, ) -> Result<Option<T>, TimerWheelError>

Cancel a previously scheduled timer

O(1) operation - directly indexes into the wheel using the timer ID.

Arguments

• timer_id - Timer ID returned from schedule_timer()

Returns

Returns the timer data if found and cancelled, or an error if the timer doesn’t exist or the timer ID is invalid.

pub fn poll( &mut self, now_ns: u64, expiry_limit: usize, output: &mut Vec<(u64, u64, T)>, ) -> usize

Poll for expired timers

Checks for timers that have expired by the given now_ns time. First cascades L1 timers that are now within L0 coverage down to L0, then polls L0 for expired timers.

Arguments

• now_ns - Current time in nanoseconds
• expiry_limit - Maximum number of expired timers to return
• output - Buffer to write expired timer tuples: (timer_id, deadline_ns, data)

Returns

Returns the number of expired timers found (may be less than expiry_limit)

pub fn advance_to(&mut self, now_ns: u64)

Advance the wheel’s current tick position without polling

Useful for synchronizing the wheel’s position when time advances without immediately processing expired timers.

pub fn current_tick_time_ns(&self) -> u64

Get the time corresponding to the next tick

Returns the absolute time (in nanoseconds) when the next tick will occur.

pub fn timer_count(&self) -> u64

Get the total number of active timers across both wheels

pub fn next_deadline(&mut self) -> Option<u64>

Get the earliest deadline among all active timers

Uses cached values when available for O(1) performance. Falls back to full wheel scans when cache is invalidated (O(ticks_per_wheel × tick_allocation)).

Returns

Returns the earliest deadline in nanoseconds, or None if no timers are scheduled.

pub fn now_ns(&self) -> u64

pub fn set_now_ns(&mut self, now_ns: u64)

pub fn worker_id(&self) -> u32

pub fn clear(&mut self)