Struct SnapshotRing 

pub struct SnapshotRing { /* private fields */ }

A fixed-capacity ring buffer of Arc<OwnedSnapshot>.

Single-producer: only one thread calls push. Multi-consumer: any thread can call latest or get_by_pos to read snapshots.

The write position is monotonically increasing (never wraps). Slot index is computed as pos % capacity. Each slot stores a position tag alongside the snapshot so that consumers can verify they are reading the slot they intended, even under concurrent producer pushes.

Implementations

impl SnapshotRing

pub fn new(capacity: usize) -> Self

Create a new ring buffer with the given capacity.

Panics

Panics if capacity < 2. A ring buffer needs at least 2 slots to be useful (one being written, one readable).

pub fn push(&self, snapshot: OwnedSnapshot) -> Option<Arc<OwnedSnapshot>>

Push a new snapshot into the ring. Single-producer only.

Returns the evicted snapshot (if any) that was displaced by this push. The caller can use this for reclamation bookkeeping.

pub fn latest(&self) -> Option<Arc<OwnedSnapshot>>

Get the latest (most recently pushed) snapshot.

Returns None only if no snapshots have been pushed yet. On overwrite races (producer wraps the slot between our write_pos read and lock acquisition), retries from the fresh write_pos. If all retries are exhausted (producer lapping the consumer), falls back to a full scan of all slots, guaranteeing Some whenever the ring is non-empty.

pub fn peek_latest(&self) -> Option<Arc<OwnedSnapshot>>

Peek the latest snapshot without mutating read-side telemetry counters.

This is intended for non-failing readiness/health checks (for example RealtimeAsyncWorld::preflight) that should not be counted as observation read failures or skew retries.

pub fn get_by_pos(&self, pos: u64) -> Option<Arc<OwnedSnapshot>>

Get a snapshot by its monotonic write position.

Returns None if the position has been evicted (overwritten) or hasn’t been written yet.

pub fn len(&self) -> usize

Number of snapshots currently stored (up to capacity).

pub fn is_empty(&self) -> bool

Whether the ring is empty.

pub fn capacity(&self) -> usize

The ring buffer capacity.

pub fn write_pos(&self) -> u64

The current monotonic write position.

pub fn oldest_retained_pos(&self) -> Option<u64>

Oldest retained write position currently available in the ring.

Returns None when no snapshots have been pushed yet.

pub fn not_available_events(&self) -> u64

Number of times an observation request found no snapshot available.

pub fn eviction_events(&self) -> u64

Number of push operations that evicted an older retained snapshot.

pub fn stale_read_events(&self) -> u64

Number of read attempts that targeted stale or not-yet-written positions.

pub fn skew_retry_events(&self) -> u64

Number of read retries caused by producer/consumer overwrite skew.