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: Pod`** — restricts payloads to plain-old-data types where every bit
17//!   pattern is valid, making torn seqlock reads harmless (no UB).
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;
56mod pod;
57pub(crate) mod ring;
58mod shutdown;
59pub(crate) mod slot;
60#[cfg(any(
61    target_os = "linux",
62    target_os = "macos",
63    target_os = "windows",
64    target_os = "freebsd",
65    target_os = "netbsd",
66    target_os = "android",
67))]
68pub mod topology;
69mod typed_bus;
70pub mod wait;
71
72pub use bus::Photon;
73pub use channel::{
74    channel, channel_bounded, channel_mpmc, Drain, MpPublisher, PublishError, Publisher,
75    Subscribable, Subscriber, SubscriberGroup, TryRecvError,
76};
77pub use pod::Pod;
78
79/// Derive macro for the [`Pod`] trait. Requires the `derive` feature.
80///
81/// ```ignore
82/// #[derive(photon_ring::DerivePod, Clone, Copy)]
83/// #[repr(C)]
84/// struct Quote { price: f64, volume: u32 }
85/// ```
86#[cfg(feature = "derive")]
87pub use photon_ring_derive::Pod as DerivePod;
88pub use shutdown::Shutdown;
89pub use typed_bus::TypedBus;
90pub use wait::WaitStrategy;
photon_ring/lib.rs

photon_ring/
lib.rs
