yo_reactor/lib.rs
1//! The shard loop.
2//!
3//! `04` section 2 is nine lines of pseudocode and this crate is those nine
4//! lines with the bookkeeping filled in. Six stages, in one order, forever:
5//!
6//! 1. hand the submission queue to the kernel, which is one syscall or none,
7//! 2. drain up to [`BATCH_MAX`] commands out of the intake lanes,
8//! 3. enter the epoch,
9//! 4. walk the batch once for the prefetch and once for the work,
10//! 5. leave the epoch, then flush one reply buffer per connection touched,
11//! 6. pick up completions and spend a bounded slice on maintenance.
12//!
13//! There is no executor here, no future, no waker, no `.await` and no work
14//! stealing. The loop is the scheduler. That is not a stylistic preference: the
15//! VLDB 2026 io_uring ladder is 16.5 thousand transactions a second when every
16//! submission is waited on and 546.5 thousand when the shard keeps going and
17//! picks completions up later, and an async runtime in the middle is how a
18//! system gives that back.
19//!
20//! ## What this crate is and is not
21//!
22//! It is the loop, the batch, the two walks, the epoch discipline and the
23//! maintenance budget. It is not the commands, the connections or the parser.
24//! Those arrive through [`Engine`], which is the seam a shard is plugged in
25//! through, and the loop does not know what a command is beyond having a key
26//! hash or not having one.
27//!
28//! ```
29//! use yo_reactor::{Engine, Flow, Reactor};
30//!
31//! struct Counting(u64);
32//!
33//! impl Engine for Counting {
34//! type Work = u64;
35//! fn key_hash(&self, w: &u64) -> Option<u64> { Some(*w) }
36//! fn prefetch(&self, _w: &u64, _hash: u64) {}
37//! fn run(&mut self, w: u64, _hash: Option<u64>) -> Flow { self.0 += w; Flow::Next }
38//! fn flush(&mut self) {}
39//! }
40//!
41//! let mut r = Reactor::inline(Counting(0));
42//! for i in 1..=10 { r.execute(i); }
43//! assert_eq!(r.engine().0, 55);
44//! ```
45
46#![deny(missing_docs)]
47
48mod budget;
49mod reactor;
50
51pub use budget::{Budget, MAINTENANCE_UNITS};
52pub use reactor::{BATCH_MAX, Engine, Flow, Reactor, Turn};