Struct Subscriber 

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

The read side of a Photon SPMC channel.

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

Implementations

impl<T: Copy> 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.

Trait Implementations

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

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Copy + Send> Send for Subscriber<T>