nexus_timer/lib.rs
1//! High-performance timer wheel with O(1) insert and cancel.
2//!
3//! `nexus-timer` provides a hierarchical timer wheel inspired by the Linux
4//! kernel's timer infrastructure (Gleixner 2016). Timers are placed into
5//! coarser slots at higher levels — no cascading, no entry movement after
6//! insertion.
7//!
8//! # Design
9//!
10//! - **No cascade:** Once placed, an entry never moves. Poll checks each
11//! entry's exact deadline. This eliminates the latency spikes that
12//! cascading timer wheels exhibit.
13//! - **Intrusive active-slot lists:** Only non-empty slots are visited
14//! during poll and next-deadline queries. No bitmap, no full scan.
15//! - **Embedded refcounting:** Lightweight `Cell<u8>` refcount per entry
16//! enables fire-and-forget timers alongside cancellable timers without
17//! external reference-counting machinery.
18//! - **Generic storage:** Parameterized over slab backend — bounded
19//! (fixed-capacity) or unbounded (growable).
20//!
21//! # Quick Start
22//!
23//! ```
24//! use std::time::{Duration, Instant};
25//! use nexus_timer::Wheel;
26//!
27//! let now = Instant::now();
28//! let mut wheel: Wheel<u64> = Wheel::unbounded(4096, now);
29//!
30//! // Schedule a timer 100ms from now
31//! let handle = wheel.schedule(now + Duration::from_millis(100), 42u64);
32//!
33//! // Cancel before it fires — get the value back
34//! let value = wheel.cancel(handle);
35//! assert_eq!(value, Some(42));
36//! ```
37
38#![warn(missing_docs)]
39
40mod entry;
41mod handle;
42mod level;
43pub mod store;
44mod wheel;
45
46pub use entry::WheelEntry;
47pub use handle::TimerHandle;
48pub use wheel::{
49 BoundedWheel, BoundedWheelBuilder, TimerWheel, UnboundedWheelBuilder, Wheel, WheelBuilder,
50};
51
52// Re-export Full for bounded wheel users
53pub use nexus_slab::Full;