Skip to main content

Module timeout_queue

Module timeout_queue 

Source
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§

BoundedTimeoutQueueBuilder
Terminal builder for a bounded TimeoutQueue.
TimeoutQueue
A fixed-duration timeout queue with O(fired) poll and O(1) exact next-deadline.
TimeoutQueueBuilder
Builder for a TimeoutQueue, mirroring WheelBuilder.
UnboundedTimeoutQueueBuilder
Terminal builder for an unbounded TimeoutQueue.

Type Aliases§

BoundedTimeoutQueue
A timeout queue backed by a fixed-capacity slab.