Struct TimeWheel 

pub struct TimeWheel { /* private fields */ }

The hierarchical time wheel (SC-029, SC-030, SC-032). See the module doc comment for the level/cascade design. All fields are private — nothing outside this module depends on the internal level/slot layout, only on arm/arm_delay/next_tick/advance_to’s documented behavior.

Implementations

impl TimeWheel

pub fn new() -> Self

pub fn arm(&mut self, at: SimTick, entry: TimerEntry)

Inserts entry, due at absolute tick at, into the correct level/slot or the far-future overflow map.

pub fn pending_ticks(&self) -> BTreeSet<SimTick>

The earliest tick with any pending entry across every level and the overflow map, or None if the wheel is entirely empty. Does not mutate the wheel (SC-032’s driver calls this before deciding whether to advance at all).

Must scan every entry in every slot, not just front(): at levels 1-3 a single slot legitimately holds entries with different absolute at values (any two ticks sharing the byte at bit-position 8*l land in the same slot regardless of their other bytes), inserted in whatever order the caller armed them — so the FIFO-front entry is not necessarily the chronologically earliest one in that slot. Every tick with an entry, ascending and without duplicates.

pub fn next_tick(&self) -> Option<SimTick>

pub fn advance_to(&mut self, tick: SimTick) -> Vec<TimerEntry>

Advances the wheel’s own current position up to tick (a no-op walk if tick <= current already), cascading any level-1+ buckets that boundary-cross along the way, then pops and returns every entry due at exactly tick. Preserves same-slot FIFO order (SC-030).

SC-026/028/031’s bounded-cost requirement: this deliberately does not walk every integer tick between the old and new current (an earlier revision did, at O(tick - current) cost — 27s wall-clock for a single 256^4-tick jump on this machine, measured before this fix). Every level-1..3 cascade can only ever fire at a tick that is a multiple of SLOTS (level 1’s own boundary — levels 2 and 3’s boundaries, SLOTS^2 and SLOTS^3, are themselves multiples of SLOTS), so every other integer tick is a guaranteed no-op for every level; this walks only the multiples of SLOTS in (old current, tick] (cascade_boundary), an O((tick - current) / SLOTS) bound — and does the far-future overflow migration exactly once per call (migrate_overflow_due_by, see its own doc comment for why once-per-call is equivalent to once-per-tick) rather than once per tick, which is what made the far-future overflow check itself O(tick - current) even though cascading alone wasn’t.

pub fn arm_delay( &mut self, now: SimTick, delay_ticks: u64, act: PendingActivation, ) -> Region

The one entry point a Suspend::Delay normalizes through (SC-029 — “without a special-cased wheel code path” is satisfied by the wheel simply never being touched for a same-delta redirect, not by an if inside arm). delay_ticks == 0 returns Region::Inactive without calling arm at all; any other delay arms at now + delay_ticks with region: Region::Active and returns Region::Active.

pub fn arm_trigger(&mut self, at: SimTick, cell: StateCellId)

SC-069: arms a delayed named-event trigger (->>#N my_event;’s scheduler-side shape) to fire at absolute tick at. Unlike arm_delay, there is no delay_ticks == 0 special case here – an undelayed -> never suspends/touches the wheel at all (it fires the trigger synchronously through the same notify_change fan-out, scheduler.md §8), so every call to this method genuinely arms the wheel.

Trait Implementations

impl Default for TimeWheel

fn default() -> Self

Returns the “default value” for a type.