Photon Ring

Seqlock-stamped inter-thread messaging for Rust. Zero-allocation broadcast channels at near-hardware latency.

Overview

How Photon Ring achieves near-hardware latency

Photon Ring is a zero-allocation pub/sub crate for Rust built around pre-allocated ring buffers with per-slot seqlock stamps. It targets the part of concurrent systems where queueing overhead dominates: market data, telemetry fanout, staged pipelines, and other hot-path broadcast workloads where every subscriber must observe every message.

The central insight is stamp-in-slot co-location: by embedding the seqlock sequence stamp directly alongside the payload in one #[repr(C, align(64))] struct, both ownership metadata and data reside within a single 64-byte cache line for payloads up to 56 bytes. Consumers validate and read in one L3 snoop instead of two, cutting coherence traffic in half.

Slot layout

                    64 bytes (one cache line)
+-----------------------------------------------------------+
|  stamp: AtomicU64  |  value: T                            |
|  (seqlock)         |  (Pod — all bit patterns valid)      |
+-----------------------------------------------------------+
For T <= 56 bytes: stamp and value share one cache line.
Larger T spills to additional lines (still correct, slightly slower).

Write protocol:                Read protocol:
  stamp = seq*2 + 1 (odd)       s1 = stamp.load(Acquire)
  fence(Release)                 if odd  → spin
  memcpy(slot.value, data)       if s1 < expected → Empty
  stamp = seq*2 + 2 (even)       if s1 > expected → Lagged
  cursor = seq (Release)         value = memcpy(slot)
                                 s2 = stamp.load(Acquire)
                                 if s1 == s2 → return value
                                 else → retry

Benchmarks

Criterion (100 samples, --release, no custom RUSTFLAGS) on two machines. Numbers are medians unless stated.

Hardware

Core operations

BusySpin wait strategy, 4096-slot ring, Criterion, 100 samples. Machine A is the Intel i7-10700KF, machine B the Apple M1 Pro.

Throughput

Sustained message rate, single publisher, single subscriber, BusySpin.

Payload scaling

At cache-line-sized payloads the copy is a few percent of latency — cross-core cache-coherence transfer dominates. The copy only becomes co-dominant in the KiB range. See full payload scaling analysis.

Where this fits

What inter-thread messaging designs cost, and which problem each one solves

Approaches

Inter-thread messaging designs usually pay for at least one expensive property on the hot path. Which one you can afford is the real choice.

Pre-allocated rings are what removed allocator overhead from this problem, and the shared sequence barrier is the classic way to order consumers on one: every consumer publishes its position, and the producer folds them into a minimum before it may overwrite a slot. That is cheap with one consumer and grows with the audience. Moving validation into each slot trades the ordering for independence — subscribers keep private cursors and never consult one another — which is also what makes per-consumer delivery contracts, dead-consumer recovery and hot attach possible, since there is no shared minimum for a stalled consumer to poison.

Fanout scaling

Delivering one message to N consumers is O(N) work somewhere — the question is where it lands. Time to publish one message and have all N consumers observe it, in nanoseconds, single-threaded and in-cache. This measures protocol overhead, not real cross-core fanout latency.

Cross-thread fanout

The table above isolates protocol cost in cache. This is the deployed shape: one producer, N consumer threads on their own cores, 100k messages, every consumer accounting for all of them. Total milliseconds, lower is better.

Capabilities

Design constraints

API Overview

Channels, buses, pipelines, and wait strategies — all composable. See docs.rs for the full reference.

SPMC channel

// Single producer, multiple consumers — the fastest path
let (mut pub_, subs) = channel::<u64>(1024);
let mut sub = subs.subscribe();

pub_.publish(42);
assert_eq!(sub.try_recv(), Ok(42));

// Bounded backpressure (publisher blocks instead of overwriting)
let (mut pub_, subs) = channel_bounded::<u64>(1024, 512);

// Multiple producers
let (mp_pub, subs) = channel_mpmc::<u64>(1024);
let mp_pub2 = mp_pub.clone();  // MpPublisher: Clone + Send + Sync

Named-topic bus

let bus = Photon::<u64>::new(1024);

let mut prices = bus.publisher("prices");
let mut trades = bus.publisher("trades");

let mut sub = bus.subscribe("prices");

prices.publish(100);
assert_eq!(sub.try_recv(), Ok(100));

Pipeline topology

let (input, pipeline) = Pipeline::builder()
    .capacity(4096)
    .input::<u64>()
    .then(|x| x * 2)       // stage 1: dedicated thread
    .then(|x| x + 1)       // stage 2: dedicated thread
    .build();

input.publish(21);

// Fan-out: diamond topology
let (input, _pipeline) = Pipeline::builder()
    .capacity(1024)
    .input::<u64>()
    .fan_out(|x| x * 2, |x| x + 100)   // two parallel branches
    .build();

Wait strategies

use photon_ring::WaitStrategy;

// Absolute lowest wakeup latency
sub.recv_with(WaitStrategy::BusySpin);

// Cooperative spinning (yields CPU between spins)
sub.recv_with(WaitStrategy::YieldSpin);

// Exponential backoff (good for mixed loads)
sub.recv_with(WaitStrategy::BackoffSpin);

// Automatically tunes based on observed latency
sub.recv_with(WaitStrategy::Adaptive);

Platform support

Get Started

From zero to a working channel in under a minute

[dependencies]
photon-ring = "2"

# Optional features
# photon-ring = { version = "2", features = ["derive", "hugepages"] }

use photon_ring::{channel, Photon};

fn main() {
    // SPMC: one publisher, multiple independent subscribers
    let (mut pub_, subs) = channel::<u64>(1024);
    let mut sub_a = subs.subscribe();
    let mut sub_b = subs.subscribe();

    pub_.publish(42);

    // Both subscribers see the same message
    assert_eq!(sub_a.try_recv(), Ok(42));
    assert_eq!(sub_b.try_recv(), Ok(42));

    // Named-topic bus
    let bus = Photon::<u64>::new(1024);
    let mut p = bus.publisher("prices");
    let mut s = bus.subscribe("prices");
    p.publish(100);
    assert_eq!(s.try_recv(), Ok(100));
}

use photon_ring::{channel, WaitStrategy};
use std::thread;

let (mut pub_, subs) = channel::<u64>(4096);
let mut sub = subs.subscribe();

let consumer = thread::spawn(move || {
    loop {
        match sub.try_recv() {
            Ok(v)  => { /* process v */ }
            Err(_) => break,
        }
    }
});

for i in 0..1_000_000 {
    pub_.publish(i);
}

consumer.join().unwrap();