low-latency-data-structures

Experimental lock-free SPSC, SPMC broadcast, and SeqLock primitives tuned for ultra-low-latency systems (HFT-style request paths, real-time telemetry, market-data fan-out, low-jitter audio).

Status: experimental (0.0.x). The public API may change on any release. Pin to an exact version if you depend on it.

What's inside

All primitives are bounded with a compile-time CAPACITY that must be a power of two. None of them allocate on the hot path. The SPMC and SeqLock primitives read with seq-number validation, so the value type must implement [bytemuck::AnyBitPattern].

Quick start

[dependencies]
low-latency-data-structures = "=0.0.3"

use low_latency_data_structures::mem::global::GlobalAllocator;

// SPSC
use low_latency_data_structures::spsc;
let (producer, consumer) =
    spsc::new::<u64, 1024, GlobalAllocator>(spsc::Options::global_mlocked());
assert!(producer.push(42).is_none());
assert_eq!(consumer.pop(), Some(42));

// SPMC broadcast
use low_latency_data_structures::spmc::{self, ReadResult};
let (producer, [mut c1, mut c2]) =
    spmc::new::<u64, 1024, 2, GlobalAllocator>(spmc::Options::global_mlocked());
producer.publish(42);
assert_eq!(c1.try_read(), ReadResult::Value(42));
assert_eq!(c2.try_read(), ReadResult::Value(42));

// SeqLock
use low_latency_data_structures::seqlock;
let (writer, reader) = seqlock::new(0u64);
writer.write(42);
assert_eq!(reader.read(), 42);

The Options argument selects the backing allocator (currently GlobalAllocator or HugepageAllocator) and per-allocator settings like mlock. Options::global_mlocked() is a shorthand for the common "global allocator, mlocked" case; use Options::builder() for anything else.

Three runnable hello-world examples ship in examples/:

cargo run --release --example spsc_hello
cargo run --release --example spmc_hello
cargo run --release --example seqlock_hello

Benchmarks

Numbers below are from this machine and this kernel cmdline. They are useful as an order-of-magnitude reference, not as a vendor-style "X ns" claim. To reproduce on your hardware, run the recipes from the justfile listed under each table.

Single-thread micro (Criterion, no cross-core traffic)

Recipes: just bench-spsc-micro, just bench-seqlock-micro, just bench-spmc-micro.

Cross-core handoff (cores 7 + 8, isolated)

Latency from the producing write to the matching consuming read, in ns.

Recipes: just bench-spsc-handoff 7,8, just bench-spmc-handoff 7,8, just bench-seqlock-handoff 7,8.

SPSC throttled-producer offered-load sweep

User-perceived (coordinated-omission-corrected) latency for a producer firing at a fixed rate, consumer draining as fast as possible:

Recipe: just bench-spsc-throttled 7,8.

SPSC cold-cache drain (regular vs hugepage)

Per-item drain cost for capacities that span L1 to deep L2/L3, after a 64 MiB flush buffer evicts every cache level:

Hugepages need vm.nr_hugepages > 0. Recipe: just bench-spsc-drain 7,8 after just enable-hugepages.

SPMC lapped recovery (CAPACITY=128, 2s run)

Producer flat out, consumer adds a fixed delay between reads. Value latency is the time taken by a successful read, Lapped latency is the cost of detecting and recovering from a lap:

Recipe: just bench-spmc-lapped 7,8.

SPMC capacity sweep (sustained producer, 2s per cell)

Single trailing consumer, value latency and lap rate as the slot ring grows:

Recipe: just bench-spmc-capacity-sweep 7,8.

Setup

CPU:        Intel i7-10750H @ 2.6 GHz, 6 cores / 12 threads
L1d/L1i:    32 KiB / 32 KiB per core
L2:         256 KiB per core
L3:         12 MiB shared
Kernel:     Linux 6.18.36 (NixOS 26.05)
cmdline:    isolcpus=7,8 nohz_full=7,8 rcu_nocbs=7,8
            intel_idle.max_cstate=0 processor.max_cstate=0
Tuning:     scaling_governor=performance on 7,8
            no_turbo=1, SMT siblings of 7 and 8 offlined (cpu 1,2)
            vm.nr_hugepages=64 (for the drain bench)

The just setup-cores 7,8 recipe applies the runtime knobs (governor, turbo, sibling offline). The boot-time knobs (isolcpus, nohz_full, rcu_nocbs, intel_idle.max_cstate=0) need to be in your kernel cmdline.

Test coverage

• basic exercises behaviour through the public API on real std::thread threads.
• loom runs the SPSC model under loom, including should-panic cases that confirm loom catches a second producer and a second consumer.
• dhat asserts zero hot-path heap allocations via dhat.
• hugepage exercises the optional mmap(MAP_HUGETLB) allocator. Needs vm.nr_hugepages > 0 on the host.

Run with just test-basic, just test-loom, just test-dhat, just test-e2e-smoke, or just test-all.

MSRV and features

• Rust 1.95 (2024 edition).
• Default features: none.
• Internal-only features (used by the test suite and by the CI examples; not intended for downstream use):
  • tests_basic, tests_loom, tests_dhat, tests_hugepage: enable the corresponding test groups.
  • _bench_utils: gates an internal bench helper module used by the bundled benchmark examples.

Other production-ready crates in this space

If you need a battle-tested, stable-API alternative today, take a look at:

• crossbeam-queue for general MPMC and SPSC bounded queues.
• ringbuf for a mature SPSC ring with blocking and split APIs.
• kanal for cross-thread async/sync channels.
• rtrb for a real-time-focused SPSC ring.

This crate is not trying to replace those. It is a focused 0.0.x experiment in squeezing the last hundred-or-so nanoseconds out of a few specific patterns with deliberate platform assumptions (x86_64, isolated cores, hugepages where relevant).

License

MIT. See LICENSE.