Module release_timer 

A process-wide release wheel: one dedicated OS thread, one min-heap of deadlines, one CancellationToken per armed deadline.

tokio::time::sleep cannot be used for release timing. Tokio parks its runtime on a wait with a millisecond timeout, and on Windows every interruptible wait is quantised to the ~15.6 ms system tick: measured on Windows 11, tokio::time::sleep(1 ms) returns after 15.96 ms and Condvar::wait_timeout(1 ms) is 14.6 ms late. std::thread::sleep is the exception — std implements it with a high-resolution waitable timer, so it lands within ~0.3 ms — but it cannot be woken early.

This module recovers accurate and interruptible in plain safe code: the thread sleeps in SLICE-bounded steps and re-reads the heap between them, and parks on an untimed Condvar — which is woken promptly — when there is nothing to wait for. End to end (the thread wakes, cancels a token, a tokio task in a select! resumes) the measured lateness on Windows 11 is p50 0.11-0.17 ms and p95 0.52-0.57 ms, against 11-13 ms for tokio::time::sleep.

Nothing here is pub, the whole module is safe code, and there is no #[cfg] outside its test module: one implementation runs on every platform. That is what lets this file move into quinn-netem, give each impaired socket its own wheel, or be replaced wholesale, without any of it being a breaking change.

Structs

Deadline 🔒

A registered deadline. Cheap to clone (one Arc + one token clone).

Entry 🔒

What a Deadline and its heap slot share.

Inner 🔒

The shared half of a wheel: what the thread and its registrars both hold an Arc to.

ReleaseTimer 🔒

An owned release wheel: one OS thread, one heap, one parker.

Slot 🔒

A heap slot. Weak, so a dropped Deadline costs a skipped pop rather than a token nobody holds.

State 🔒

Everything the release thread and its registrars share under one lock.

Enums

Parker 🔒

How the thread waits when a deadline is armed.

Wait 🔒

What the thread should do next. Pure — no clock read, no lock — so the_wait_plan_never_overshoots pins the never-overshoot rule without timing anything.

Constants

SLICE 🔒

How long the release thread may sleep without re-reading the heap.

SWEEP_INTERVAL 🔒

Minimum interval between two sweeps.

SWEEP_MIN_LEN 🔒

Heap length below which the sweep never runs.

Functions

arm_at 🔒

Register at with the process-wide wheel.

backend 🔒

Which primitive the process-wide wheel’s thread waits on, or None if it was never constructed. This is what crate::instrument::release_timer_backend returns.

plan 🔒

Decide the next wait from a clock reading and the head of the heap.

run 🔒

The release thread’s body.

shared 🔒

The process-wide wheel, constructed on first use. Never dropped: it lives in a static OnceLock<ReleaseTimer>, so its thread is never joined and the atexit joins a thread that holds a lock hazard cannot arise.

started 🔒

Whether the process-wide wheel has been constructed.