photon_ring/
lib.rs

1// Copyright 2026 Photon Ring Contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! # Photon Ring
5//!
6//! Ultra-low-latency SPMC pub/sub using seqlock-stamped ring buffers.
7//!
8//! `no_std` compatible (requires `alloc`). The [`topology`] module uses
9//! OS threads and is available on Linux, macOS, Windows, and other
10//! supported platforms.
11//!
12//! ## Key design
13//!
14//! - **Seqlock per slot** — stamp and payload share a cache line; readers never
15//!   take a lock, writers never allocate.
16//! - **`T: Copy`** — enables safe `memcpy` reads; torn reads are detected and
17//!   retried (no `Drop` / double-free concerns).
18//! - **Per-consumer cursor** — zero contention between subscribers.
19//! - **Single-producer** — no write-side synchronisation; the seqlock invariant
20//!   is upheld by `&mut self` on [`Publisher::publish`].
21//!
22//! ## Quick start
23//!
24//! ```
25//! // Low-level SPMC channel
26//! let (mut pub_, subs) = photon_ring::channel::<u64>(64);
27//! let mut sub = subs.subscribe();
28//! pub_.publish(42);
29//! assert_eq!(sub.try_recv(), Ok(42));
30//!
31//! // Named-topic bus
32//! let bus = photon_ring::Photon::<u64>::new(64);
33//! let mut p = bus.publisher("topic-a");
34//! let mut s = bus.subscribe("topic-a");
35//! p.publish(7);
36//! assert_eq!(s.try_recv(), Ok(7));
37//! ```
38
39#![no_std]
40
41extern crate alloc;
42
43#[cfg(any(
44    target_os = "linux",
45    target_os = "macos",
46    target_os = "windows",
47    target_os = "freebsd",
48    target_os = "netbsd",
49    target_os = "android",
50))]
51pub mod affinity;
52mod bus;
53pub mod channel;
54#[cfg(all(target_os = "linux", feature = "hugepages"))]
55pub mod mem;
56pub(crate) mod ring;
57mod shutdown;
58pub(crate) mod slot;
59#[cfg(any(
60    target_os = "linux",
61    target_os = "macos",
62    target_os = "windows",
63    target_os = "freebsd",
64    target_os = "netbsd",
65    target_os = "android",
66))]
67pub mod topology;
68mod typed_bus;
69pub mod wait;
70
71pub use bus::Photon;
72pub use channel::{
73    channel, channel_bounded, channel_mpmc, Drain, MpPublisher, PublishError, Publisher,
74    Subscribable, Subscriber, SubscriberGroup, TryRecvError,
75};
76pub use shutdown::Shutdown;
77pub use typed_bus::TypedBus;
78pub use wait::WaitStrategy;
photon_ring/lib.rs

photon_ring/
lib.rs
