Struct Subscriber 

pub struct Subscriber<T: Pod> { /* private fields */ }

The read side of a Photon SPMC channel.

Each subscriber has its own cursor — no contention between consumers.

Implementations

impl<T: Pod> Subscriber<T>

pub fn try_recv(&mut self) -> Result<T, TryRecvError>

Try to receive the next message without blocking.

pub fn recv(&mut self) -> T

Spin until the next message is available and return it.

Uses a two-phase spin strategy: bare spin for the first 64 iterations (minimum wakeup latency, ~0 ns reaction time), then PAUSE-based spin (saves power, yields to SMT sibling). On Skylake+, PAUSE adds ~140 cycles of delay per iteration — the bare-spin phase avoids this penalty when the message arrives quickly (typical for cross-thread pub/sub).

pub fn recv_with(&mut self, strategy: WaitStrategy) -> T

Block until the next message using the given WaitStrategy.

Unlike recv(), which hard-codes a two-phase spin, this method delegates idle behaviour to the strategy — enabling yield-based, park-based, or adaptive waiting.

Example

use photon_ring::{channel, WaitStrategy};

let (mut p, s) = channel::<u64>(64);
let mut sub = s.subscribe();
p.publish(7);
assert_eq!(sub.recv_with(WaitStrategy::BusySpin), 7);

pub fn latest(&mut self) -> Option<T>

Skip to the latest published message (discards intermediate ones).

Returns None only if nothing has been published yet. Under heavy producer load, retries internally if the target slot is mid-write.

pub fn pending(&self) -> u64

How many messages are available to read (capped at ring capacity).

pub fn total_received(&self) -> u64

Total messages successfully received by this subscriber.

pub fn total_lagged(&self) -> u64

Total messages lost due to lag (consumer fell behind the ring).

pub fn receive_ratio(&self) -> f64

Ratio of received to total (received + lagged). Returns 0.0 if no messages have been processed.

pub fn recv_batch(&mut self, buf: &mut [T]) -> usize

Receive up to buf.len() messages in a single call.

Messages are written into the provided slice starting at index 0. Returns the number of messages received. On lag, the cursor is advanced and filling continues from the oldest available message.

pub fn drain(&mut self) -> Drain<'_, T>

Returns an iterator that drains all currently available messages. Stops when no more messages are available. Handles lag transparently by retrying after cursor advancement.

pub fn tracker(&self) -> Option<Arc<Padded<AtomicU64>>>

Get this subscriber’s cursor tracker for use in a DependencyBarrier.

Returns None if the subscriber was created on a lossy channel without subscribe_tracked(). Use subscribe_tracked() to ensure a tracker is always present.

pub fn try_recv_gated( &mut self, barrier: &DependencyBarrier, ) -> Result<T, TryRecvError>

Try to receive the next message, but only if all upstream subscribers in the barrier have already processed it.

Returns TryRecvError::Empty if the upstream barrier has not yet advanced past this subscriber’s cursor, or if no new message is available from the ring.

Example

use photon_ring::{channel, DependencyBarrier, TryRecvError};

let (mut pub_, subs) = channel::<u64>(64);
let mut upstream = subs.subscribe_tracked();
let barrier = DependencyBarrier::from_subscribers(&[&upstream]);
let mut downstream = subs.subscribe();

pub_.publish(42);

// Downstream can't read — upstream hasn't consumed it yet
assert_eq!(downstream.try_recv_gated(&barrier), Err(TryRecvError::Empty));

upstream.try_recv().unwrap();

// Now downstream can proceed
assert_eq!(downstream.try_recv_gated(&barrier), Ok(42));

pub fn recv_gated(&mut self, barrier: &DependencyBarrier) -> T

Blocking receive gated by a dependency barrier.

Spins until all upstream subscribers in the barrier have processed the next message, then reads and returns it. On lag, the cursor is advanced and the method retries.

Example

use photon_ring::{channel, DependencyBarrier};

let (mut pub_, subs) = channel::<u64>(64);
let mut upstream = subs.subscribe_tracked();
let barrier = DependencyBarrier::from_subscribers(&[&upstream]);
let mut downstream = subs.subscribe();

pub_.publish(99);
upstream.try_recv().unwrap();

assert_eq!(downstream.recv_gated(&barrier), 99);

Trait Implementations

impl<T: Pod> Drop for Subscriber<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Pod> Send for Subscriber<T>