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::{self, new, ReadResult};
25//! use low_latency_data_structures::mem::global::GlobalAllocator;
26//!
27//! let (producer, mut consumer) = new::<u64, 1024, GlobalAllocator>(
28//!     spmc::Options::global_mlocked(),
29//! );
30//! producer.publish(42);
31//! assert_eq!(consumer.try_read(), ReadResult::Value(42));
32//! ```
33//!
34//! # Soundness
35//!
36//! All public APIs are safe to call. Internally the crate uses `unsafe` to
37//! implement seqlock-style validation: a reader may observe a torn or stale
38//! value, but the surrounding sequence-number check rejects it before it
39//! escapes the public API. To make torn reads observable rather than
40//! undefined, every value type carried by these primitives must implement
41//! [`bytemuck::AnyBitPattern`].
42//!
43//! The SPSC queue is exercised under [loom](https://crates.io/crates/loom);
44//! see the README for the per-primitive test coverage matrix.
45
46#![warn(missing_docs)]
47#![warn(unsafe_op_in_unsafe_fn)]
48#![cfg_attr(docsrs, feature(doc_cfg))]
49
50#[cfg(not(target_os = "linux"))]
51compile_error!(
52    "This crate only supports Linux operating systems. See: https://github.com/YawKar/low-latency-data-structures/issues/9"
53);
54
55#[cfg(feature = "_bench_utils")]
56#[doc(hidden)]
57pub mod bench;
58pub mod mem;
59pub mod seqlock;
60mod shim;
61#[cfg(not(feature = "tests_loom"))]
62pub mod spmc;
63pub mod spsc;
64
65#[cfg(test)]
66#[cfg(feature = "tests_dhat")]
67#[global_allocator]
68static ALLOC: dhat::Alloc = dhat::Alloc;
low_latency_data_structures/lib.rs

low_latency_data_structures/
lib.rs
