congestion/lib.rs
1//! Pluggable congestion control for the RCP tool family.
2//!
3//! This crate exposes a [`Controller`] trait that encapsulates a
4//! congestion-control algorithm — consuming operation-completion
5//! [`Sample`]s and emitting concurrency / rate [`Decision`]s. The trait is
6//! intentionally small and synchronous so algorithms can be implemented and
7//! tested without any I/O, async runtime, or wall-clock dependence.
8//!
9//! Three concentric layers are envisioned for integration with the rcp /
10//! rrm / rlink / filegen tools:
11//!
12//! 1. **Algorithm** — the `Controller` trait and its implementations; pure.
13//! 2. **Control loop** — plumbing that collects samples from the hot path,
14//! drives the controller on a fixed tick, and publishes decisions. Lives
15//! outside this crate (in `throttle` or a thin adapter) and is not part
16//! of Phase 1.
17//! 3. **Enforcement** — the existing `throttle` token buckets and
18//! semaphores, with their limits driven by the control loop.
19//!
20//! # Built-in controllers
21//!
22//! - [`NoopController`] — never limits. Default when congestion control is
23//! disabled.
24//! - [`FixedController`] — honors a static concurrency/rate budget. Mirrors
25//! the existing manual `--ops-throttle` / `--iops-throttle` knobs and is
26//! the regression baseline for adaptive algorithms.
27//! - [`RatioController`] — adaptive controller that tracks queueing-delay
28//! inflation by comparing two windowed latency percentiles (current vs
29//! baseline) and adjusts the concurrency cap to stay at the onset of
30//! inflation. Inspired by TCP Vegas.
31//!
32//! Additional adaptive variants (for example BBR-style) can be layered
33//! on the same trait without changes to the enforcement or control-loop
34//! layers.
35//!
36//! # Testing
37//!
38//! The [`sim`] module provides a deterministic single-bottleneck simulator
39//! that drives any `Controller` through a configured scenario and returns a
40//! trace of samples and decisions. See the module docs for the model.
41
42mod control_loop;
43mod controller;
44mod fixed;
45pub mod format;
46mod histogram;
47mod measurement;
48mod noop;
49mod ratio;
50pub mod sim;
51pub mod testing;
52
53pub use control_loop::{ControlUnit, DEFAULT_TICK_INTERVAL, RoutingSink, RoutingSinkBuilder};
54pub use controller::{Controller, ControllerSnapshot, Decision, Outcome, Sample};
55pub use fixed::FixedController;
56pub use histogram::{
57 HDR_HIGHEST_TRACKABLE_MICROS, HDR_LOWEST_DISCERNIBLE_MICROS, HDR_SIGNIFICANT_FIGURES,
58 HistogramAccumulator,
59};
60pub use measurement::{
61 MetadataOp, N_META_OPS, N_META_RESOURCES, N_SIDES, Probe, ResourceKind, SampleSink, Side,
62 clear_sample_sink, install_sample_sink,
63};
64pub use noop::NoopController;
65pub use ratio::{RatioConfig, RatioController};