dynomite/runtime/mod.rs
1//! Runtime primitives for bounded back-pressure.
2//!
3//! The dispatcher and other internal pipelines need to refuse work fast
4//! when downstream stages cannot keep up, rather than buffer requests
5//! indefinitely and grow process memory without bound. This module
6//! provides two complementary tools, modelled after the building blocks
7//! used by the Riak Core stack:
8//!
9//! * [`Sidejob`] wraps a per-stage worker actor with a fixed-size
10//! tokio mailbox. Submissions to a full mailbox return
11//! [`SidejobError::Overloaded`] immediately so the caller can fail
12//! fast (the moral equivalent of a 503).
13//! * [`Throttle`] is a token-bucket admission control gate. Internal
14//! queues call [`Throttle::try_acquire`] to fast-fail or
15//! [`Throttle::acquire`] to wait for tokens to refill at a
16//! configured rate.
17//!
18//! Both tools register Prometheus metric families against the default
19//! process-wide registry the first time they are constructed:
20//!
21//! * `sidejob_overload_total{name="..."}` - counter, incremented every
22//! time a submit is rejected because the mailbox is full.
23//! * `throttle_wait_seconds{queue="..."}` - histogram (1 ms .. 10 s),
24//! recording the time a caller waited inside
25//! [`Throttle::acquire`] before tokens became available.
26
27mod metrics;
28mod sidejob;
29mod throttle;
30
31pub use sidejob::{Sidejob, SidejobError};
32pub use throttle::{Throttle, ThrottleError};