photon-ring 3.0.0

// Copyright 2026 Photon Ring Contributors
// SPDX-License-Identifier: MIT OR Apache-2.0

//! # Photon Ring
//!
//! Ultra-low-latency SPMC/MPMC pub/sub using stamped ring buffers.
//!
//! `no_std` compatible (requires `alloc`). The [`topology`] module uses
//! OS threads and is available on Linux, macOS, Windows, and other
//! supported platforms.
//!
//! ## Key design
//!
//! - **Seqlock per slot** — stamp and payload share a cache line; readers never
//!   take a lock, writers never allocate.
//! - **`T: Pod`** — restricts payloads to plain-old-data types that carry no
//!   padding and where every bit pattern is valid, so a torn seqlock read
//!   yields a value that is discarded rather than an invalid one.
//! - **Per-consumer cursor** — zero contention between subscribers.
//! - **Single-producer** — no write-side synchronisation; the seqlock invariant
//!   is upheld by `&mut self` on [`Publisher::publish`].
//! - **`atomic-slots` feature** — formally sound variant that uses `AtomicU64` stripes
//!   instead of `write_volatile`. Zero cost on x86-64. See the `atomic-slots` feature flag.
//! - **Arbitrary capacity** — any ring size >= 2 via Lemire fastmod; power-of-two
//!   uses bitwise AND (zero regression).
//! - **Companion crates** — `photon-ring-async` for runtime-agnostic async wrappers,
//!   `photon-ring-metrics` for framework-agnostic observability.
//!
//! ## Which ring
//!
//! - [`channel()`] — lossy `Pod` broadcast; the publisher never blocks, and a
//!   subscriber that falls behind observes `Lagged { skipped }`.
//! - [`channel_bounded()`] — per-consumer contracts on one ring:
//!   [`subscribe()`](Subscribable::subscribe) gates the publisher and loses
//!   nothing, [`subscribe_lossy()`](Subscribable::subscribe_lossy) can never
//!   stall it.
//! - [`channel_mpmc()`] — many producing threads; delivery is lossy only.
//! - [`event_channel()`] — payloads that own heap data (`String`, `Vec`,
//!   enums); slots are mutated in place and every subscriber gates the
//!   publisher.
//! - [`Photon`] / [`TypedBus`] — string-keyed topics, each an independent
//!   lossy ring.
//! - [`topology`] — dedicated-thread pipelines and terminal consumers.
//!
//! ## Quick start
//!
//! ```
//! // Low-level SPMC channel
//! let (mut pub_, subs) = photon_ring::channel::<u64>(64);
//! let mut sub = subs.subscribe();
//! pub_.publish(42);
//! assert_eq!(sub.try_recv(), Ok(42));
//!
//! // Named-topic bus
//! let bus = photon_ring::Photon::<u64>::new(64);
//! let mut p = bus.publisher("topic-a");
//! let mut s = bus.subscribe("topic-a");
//! p.publish(7);
//! assert_eq!(s.try_recv(), Ok(7));
//! ```

#![no_std]

extern crate alloc;

#[cfg(any(
    target_os = "linux",
    target_os = "macos",
    target_os = "windows",
    target_os = "freebsd",
    target_os = "netbsd",
    target_os = "android",
))]
pub mod affinity;
pub mod barrier;
mod bus;
pub mod channel;
pub mod event;
#[cfg(all(target_os = "linux", feature = "hugepages"))]
pub mod mem;
mod pod;
pub(crate) mod ring;
mod shutdown;
pub(crate) mod slot;
#[cfg(any(
    target_os = "linux",
    target_os = "macos",
    target_os = "windows",
    target_os = "freebsd",
    target_os = "netbsd",
    target_os = "android",
))]
pub mod topology;
mod typed_bus;
pub mod wait;

pub use barrier::DependencyBarrier;
pub use bus::Photon;
pub use channel::{
    channel, channel_bounded, channel_mpmc, Drain, MpPublisher, PublishError, Publisher,
    Subscribable, Subscriber, TryRecvError,
};
pub use event::{event_channel, EventPublisher, EventSubscribable, EventSubscriber};
pub use pod::Pod;
pub use ring::Padded;

/// Derive macro for the [`Pod`] trait. Requires the `derive` feature.
///
/// ```ignore
/// #[derive(photon_ring::DerivePod, Clone, Copy)]
/// #[repr(C)]
/// struct Quote { price: f64, volume: u32 }
/// ```
#[cfg(feature = "derive")]
pub use photon_ring_derive::Pod as DerivePod;

/// Derive macro that generates a Pod-compatible wire struct from a domain struct.
///
/// Given a struct with `bool`, `Option<numeric>`, `usize`/`isize`, and
/// `#[repr(u8)]` enum fields, generates `{Name}Wire` plus `From` conversions.
/// Structs without enum fields get safe `From` impls in both directions;
/// structs with enum fields get `From<Domain> for Wire` (safe) and
/// `Wire::into_domain()` (unsafe). Requires the `derive` feature.
///
/// ```ignore
/// #[derive(photon_ring::DeriveMessage)]
/// struct Order { price: f64, side: Side, filled: bool, tag: Option<u32> }
/// // Generates: OrderWire, From<Order> for OrderWire, From<OrderWire> for Order
/// ```
#[cfg(feature = "derive")]
pub use photon_ring_derive::Message as DeriveMessage;

pub use shutdown::Shutdown;
pub use typed_bus::TypedBus;
pub use wait::WaitStrategy;