Crate photon_ring 

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() gates the publisher and loses nothing, 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));

Re-exports

pub use barrier::DependencyBarrier;

pub use channel::channel;

pub use channel::channel_bounded;

pub use channel::channel_mpmc;

pub use channel::Drain;

pub use channel::MpPublisher;

pub use channel::PublishError;

pub use channel::Publisher;

pub use channel::Subscribable;

pub use channel::Subscriber;

pub use channel::TryRecvError;

pub use event::event_channel;

pub use event::EventPublisher;

pub use event::EventSubscribable;

pub use event::EventSubscriber;

pub use wait::WaitStrategy;

Modules

affinity

CPU core affinity helpers for deterministic cross-core latency.

barrier

Consumer dependency barriers for pipeline-style ordering.

channel

event

A ring for values that are not Pod.

mem

Platform-specific memory control for ring buffer allocation.

topology

Builder-pattern topology for multi-stage processing pipelines.

wait

Wait strategies for blocking receive operations.

Structs

Padded

Cache-line padding to prevent false sharing between hot atomics.

Photon

Named-topic pub/sub bus.

Shutdown

A shared shutdown signal for coordinating graceful termination.

TypedBus

A topic bus that supports different message types per topic.

Traits

Pod

Marker trait for types safe to use with seqlock-stamped ring buffers.

Derive Macros

DeriveMessage

Derive macro that generates a Pod-compatible wire struct from a domain struct.

DerivePod

Derive macro for the Pod trait. Requires the derive feature.