Expand description
Fixed-duration timeout queue — a sorted front-end over the wheel machinery.
TimeoutQueue<T, S> schedules every timer with the same duration, fixed
at construction. Because the duration is constant and the clock is monotone,
deadlines are monotone in insertion order: appending each new entry at the
tail of one intrusive DLL keeps the list sorted with no comparisons. Poll
then walks from the head and stops at the first not-due entry — O(fired),
not O(population) as the wheel’s per-entry scan is. next_deadline() is the
head’s deadline: exact, O(1), no cache.
§When to use this instead of TimerWheel
A wheel earns its keep when deadlines are arbitrary — timers interleaved
among earlier and later expirations. But a large class of callers schedule
one fixed timeout for everything (a flat 5 s deadline on every item).
For that workload the wheel buckets by deadline and walks buckets to solve
an ordering problem that does not exist. TimeoutQueue exploits the single
duration directly.
§The invariant is structural, not documented
There is no per-call deadline parameter anywhere in this API. Deadlines
are computed internally as now + timeout. Out-of-order insertion is
unrepresentable, not merely prohibited — one caller passing a shorter
deadline would break ordering and fire timers late, the worst failure shape
because it is invisible until it matters. A debug_assert! on insert is the
backstop for clock weirdness (a now that goes backwards).
§Reuse
WheelEntry, TimerHandle, the slab
store traits, and the DLL splice logic (WheelSlot) are
shared verbatim with the wheel — this front-end is the same machinery with
one head/tail pair in place of Vec<Level>, and the whole min_deadline
cache removed (the head is the min).
Structs§
- Bounded
Timeout Queue Builder - Terminal builder for a bounded
TimeoutQueue. - Timeout
Queue - A fixed-duration timeout queue with O(fired) poll and O(1) exact next-deadline.
- Timeout
Queue Builder - Builder for a
TimeoutQueue, mirroringWheelBuilder. - Unbounded
Timeout Queue Builder - Terminal builder for an unbounded
TimeoutQueue.
Type Aliases§
- Bounded
Timeout Queue - A timeout queue backed by a fixed-capacity slab.