Struct TopicRing 

pub struct TopicRing { /* private fields */ }

FIFO ring of ObservedEvent keyed by cursor. Single owner; not Send + Sync on its own — wrap in Arc<RwLock<…>> for cross-task access.

Implementations

impl TopicRing

pub fn new(topic: impl Into<String>, capacity: usize, reset_epoch: u64) -> Self

Construct a ring with the given capacity for a specific topic and reset epoch. Cursors start at 1.

pub fn with_base( topic: impl Into<String>, capacity: usize, reset_epoch: u64, base: u64, ) -> Self

Construct a ring whose first cursor is base (clamped to ≥ 1).

pub fn base(&self) -> u64

The first cursor this ring hands out.

pub fn set_reset_epoch(&mut self, reset_epoch: u64)

Move the ring to a new reset_epoch. Events already buffered keep the epoch they were captured under; new pushes and every read carry the new one.

pub fn topic(&self) -> &str

Topic name this ring captures (e.g. "orders").

pub fn reset_epoch(&self) -> u64

Current reset_epoch.

pub fn len(&self) -> usize

Number of events currently buffered.

pub fn is_empty(&self) -> bool

Whether the ring contains no events.

pub fn head_cursor(&self) -> u64

Smallest cursor currently buffered. Equal to next_cursor when empty.

pub fn next_cursor(&self) -> u64

Cursor that the next push will use. Useful in tests.

pub fn push(&mut self, payload: Value, received_at: String) -> u64

Push a new event with the given payload + RFC 3339 receive timestamp. Returns the assigned cursor. If the ring is at capacity, the oldest event is evicted (and head_cursor advances).

pub fn read_since(&self, since: u64, limit: usize) -> ReadResult

Read events whose cursor is strictly greater than since, capped at limit. since == 0 means “everything currently buffered”, and so does any cursor below this ring’s base (it belongs to a previous process; the epoch change tells the client so).

Returns ReadResult::CursorExpired when events the caller has not seen were evicted, or when since is past the newest cursor this ring has handed out — a cursor this ring never issued, so “caught up” would be a lie that parks the client forever.

Trait Implementations

impl Debug for TopicRing

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.