nexus_queue/
lib.rs

1//! High-performance lock-free queues for latency-critical applications.
2//!
3//! `nexus-queue` provides bounded SPSC (single-producer, single-consumer) queues
4//! optimized for trading systems and other low-latency workloads.
5//!
6//! # Quick Start
7//!
8//! ```
9//! use nexus_queue::spsc;
10//!
11//! let (mut tx, mut rx) = spsc::ring_buffer::<u64>(1024);
12//!
13//! tx.push(42).unwrap();
14//! assert_eq!(rx.pop(), Some(42));
15//! ```
16//!
17//! # Implementations
18//!
19//! Two SPSC implementations are available with different performance
20//! characteristics depending on hardware topology:
21//!
22//! - **index** (default): Cached head/tail indices on separate cache lines
23//! - **slot**: Per-slot lap counters on the same cache line as data
24//!
25//! The key difference is cache line ownership. The index-based design has
26//! producer and consumer writing to separate cache lines, while slot-based
27//! has both writing to the same cache line. Which performs better depends
28//! on your NUMA configuration and cache hierarchy.
29//!
30//! **Benchmark both on your target hardware.**
31//!
32//! ```toml
33//! # Use slot-based implementation
34//! nexus-queue = { version = "...", features = ["slot-based"] }
35//! ```
36//!
37//! # Feature Flags
38//!
39//! - `spsc-slot`: Use slot-based implementation for top-level re-exports
40
41#![deny(unsafe_op_in_unsafe_fn)]
42#![warn(missing_docs, missing_debug_implementations)]
43
44use core::fmt;
45
46pub mod spsc;
47
48/// Error returned when pushing to a full queue.
49///
50/// Contains the value that could not be pushed, returning ownership to the caller.
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub struct Full<T>(pub T);
53
54impl<T> Full<T> {
55    /// Returns the value that could not be pushed.
56    pub fn into_inner(self) -> T {
57        self.0
58    }
59}
60
61impl<T> fmt::Display for Full<T> {
62    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
63        write!(f, "queue is full")
64    }
65}
66
67impl<T: fmt::Debug> std::error::Error for Full<T> {}
nexus_queue/lib.rs

nexus_queue/
lib.rs
