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//! Fully `no_std` compatible (requires `alloc`). Every type — including the
9//! named-topic [`Photon`] bus — works without the standard library.
10//!
11//! ## Key design
12//!
13//! - **Seqlock per slot** — stamp and payload share a cache line; readers never
14//! take a lock, writers never allocate.
15//! - **`T: Copy`** — enables safe `memcpy` reads; torn reads are detected and
16//! retried (no `Drop` / double-free concerns).
17//! - **Per-consumer cursor** — zero contention between subscribers.
18//! - **Single-producer** — no write-side synchronisation; the seqlock invariant
19//! is upheld by `&mut self` on [`Publisher::publish`].
20//!
21//! ## Quick start
22//!
23//! ```
24//! // Low-level SPMC channel
25//! let (mut pub_, subs) = photon_ring::channel::<u64>(64);
26//! let mut sub = subs.subscribe();
27//! pub_.publish(42);
28//! assert_eq!(sub.try_recv(), Ok(42));
29//!
30//! // Named-topic bus
31//! let bus = photon_ring::Photon::<u64>::new(64);
32//! let mut p = bus.publisher("topic-a");
33//! let mut s = bus.subscribe("topic-a");
34//! p.publish(7);
35//! assert_eq!(s.try_recv(), Ok(7));
36//! ```
37
38#![no_std]
39
40extern crate alloc;
41
42#[cfg(any(
43 target_os = "linux",
44 target_os = "macos",
45 target_os = "windows",
46 target_os = "freebsd",
47 target_os = "netbsd",
48 target_os = "android",
49))]
50pub mod affinity;
51mod bus;
52pub mod channel;
53#[cfg(all(target_os = "linux", feature = "hugepages"))]
54pub mod mem;
55pub(crate) mod ring;
56pub(crate) mod slot;
57mod typed_bus;
58pub mod wait;
59
60pub use bus::Photon;
61pub use channel::{
62 channel, channel_bounded, channel_mpmc, MpPublisher, PublishError, Publisher, Subscribable,
63 Subscriber, SubscriberGroup, TryRecvError,
64};
65pub use typed_bus::TypedBus;
66pub use wait::WaitStrategy;