low_latency_data_structures/lib.rs
1//! Experimental lock-free SPSC, SPMC broadcast, and SeqLock primitives tuned
2//! for ultra-low-latency systems (HFT-style request paths, real-time
3//! telemetry, market-data fan-out, low-jitter audio).
4//!
5//! The crate is **experimental** (`0.0.x`) and the public API may break on
6//! any release. Pin to an exact version if you depend on it.
7//!
8//! # Primitives
9//!
10//! - [`spsc`] - single-producer, single-consumer bounded FIFO queue.
11//! - [`spmc`] - single-producer, multi-consumer broadcast queue. Every
12//! consumer observes every value the producer publishes, unless the
13//! consumer falls behind by more than `CAPACITY` slots (in which case it
14//! sees a [`spmc::ReadResult::Lapped`] and jumps to the latest slot).
15//! - [`seqlock`] - single-writer, multi-reader cell. Readers spin-loop on a
16//! sequence number until they observe a consistent value.
17//!
18//! All primitives are bounded with a power-of-two `CAPACITY` (compile-time
19//! enforced), allocate up front, and never block or allocate on the hot path.
20//!
21//! # Quick start
22//!
23//! ```
24//! use low_latency_data_structures::spmc::{new, ReadResult};
25//!
26//! let (producer, [mut consumer]) = new::<u64, 1024, 1>();
27//! producer.publish(42);
28//! assert_eq!(consumer.try_read(), ReadResult::Value(42));
29//! ```
30//!
31//! # Soundness
32//!
33//! All public APIs are safe to call. Internally the crate uses `unsafe` to
34//! implement seqlock-style validation: a reader may observe a torn or stale
35//! value, but the surrounding sequence-number check rejects it before it
36//! escapes the public API. To make torn reads observable rather than
37//! undefined, every value type carried by these primitives must implement
38//! [`bytemuck::AnyBitPattern`].
39//!
40//! The SPSC queue is exercised under [loom](https://crates.io/crates/loom);
41//! see the README for the per-primitive test coverage matrix.
42
43#![warn(missing_docs)]
44#![warn(unsafe_op_in_unsafe_fn)]
45#![cfg_attr(docsrs, feature(doc_cfg))]
46
47#[cfg(feature = "_bench_utils")]
48#[doc(hidden)]
49pub mod bench;
50mod mem;
51pub mod seqlock;
52mod shim;
53pub mod spmc;
54pub mod spsc;
55
56#[cfg(test)]
57#[cfg(feature = "tests_dhat")]
58#[global_allocator]
59static ALLOC: dhat::Alloc = dhat::Alloc;