Timer wheel rules

The rules the timer wheel follows: its slots, the order timers fire in, and how it schedules, cancels, grows and fails. Why it's built this way is on Timer wheel.

Slots and advancing

• 1,024 slots, one millisecond each. A timer sits in the slot its due time falls in, modulo 1,024.
• Advancing walks every millisecond since the last advance and fires the timers due in it. A timer a turn of the wheel or more away waits in its slot and is passed over until its time comes.
• An empty wheel jumps straight to now.

Scheduling and firing

Rule	Holds
Order	Earliest first; within one millisecond, in the order they were scheduled
A time already past	Fires on the next advance, reported with that next millisecond as its due time
A handle	Carries a generation, so a handle kept after its timer fired, or after its slot was reused, cancels nothing; the default handle is no timer
Cancel	Returns false for a timer that fired, one already cancelled, or no timer
Growth	Storage starts at the capacity the owner gives, 16 by default, and doubles when full; freed storage is reused, never shrunk
Allocation	None for scheduling and firing once storage has grown to its peak

When a timer throws

The timer that threw is gone, and the wheel stops at the millisecond before it, so the rest due in that millisecond fire on the next advance.

Known edges

• The wheel isn't thread-safe; only its owner uses it, on its own thread.
• Cancelling isn't measured for allocation; scheduling and firing are.

Where the code lives

Piece	Path
The wheel	Source/NexusTomorrow.Maps/Timing/TimerWheel.cs
Handles and the handler	Source/NexusTomorrow.Maps/Timing/
Tests	Tests/NexusTomorrow.Maps.Tests/Timing/