Struct Ring 

pub struct Ring { /* private fields */ }

A fixed-capacity, fleet-wide append-only log keyed on KIND byte.

V0 is single-process; V1 is SHM-backed. The API is the same.

Implementations

impl Ring

pub fn new<T: OrbitTyped>() -> Self

Create the process-local ring declared by T::RING_SPEC for a single-member fleet.

pub fn new_for_fleet<T: OrbitTyped>(fleet_capacity: u16) -> Self

Create the process-local ring declared by T::RING_SPEC with the physical lane count required by fleet_capacity.

pub fn kind(&self) -> u8

The KIND byte this ring carries (equals T::KIND).

pub fn capacity(&self) -> usize

Total slot count — fixed at construction.

pub fn payload_capacity(&self) -> usize

Maximum inline payload bytes for this ring lane.

pub fn spec(&self) -> RingSpec

pub fn head(&self) -> u64

Head of the sole shared lane, or lane zero for a per-node ring.

pub fn lane_count(&self) -> usize

Number of physical writer lanes in this ring.

pub fn lane_head(&self, node_id: NodeId) -> u64

Current head for node_id’s logical lane.

pub fn next_version(&self) -> u64

Allocate one non-zero semantic version shared by every writer lane.

This counter is independent of physical ring positions. Semantic layers can use it when per-node lanes need one deterministic last-write-wins order.

pub fn current_version(&self) -> u64

Last semantic version allocated for this ring.

pub fn write( &self, node_id: NodeId, frame_kind: u8, ver: u64, payload: Bytes, ) -> NetId64

Append a frame. Atomically reserves the next counter, mints the NetId64, and writes the frame into the corresponding slot. Returns the minted id.

frame_kind is the message class byte (V0: pass 0). ver is the version / tick at write time (V0: caller’s choice).

pub fn write_batch( &self, node_id: NodeId, frame_kind: u8, ver: u64, payloads: Vec<Bytes>, ) -> Vec<NetId64>

Append a contiguous batch to one lane and return its consecutive ids.

Per-node and shared-ordered lanes expose the new head only after the whole batch commits. An empty batch is a no-op. A batch larger than the ring is rejected because its first frames could not remain addressable when the method returns.

pub fn read(&self, id: NetId64) -> Option<Frame>

Read the slot that the given NetId64’s counter points at.

Returns:

• Some(frame) if the slot’s stored id matches the queried id exactly (the slot has not been overwritten by a later writer).
• None if the slot is empty, has wrapped past, or holds a different id than the one asked for.

pub fn read_head(&self) -> Option<Frame>

Read the most recent frame, regardless of who wrote it. Useful for “what’s the current state?” — ignores counter-by-counter walking.

pub fn read_at(&self, counter: u64) -> Option<Frame>

Read whatever frame currently occupies the slot at counter % capacity, regardless of which counter is stored in it. Used by walking readers that need slot-by-slot access without knowing the writer’s NetId64 ahead of time.

Returns None if the slot is empty.

pub fn reset(&self)

Clear all slots and reset every lane head to zero.

Intended for owner-controlled boot-time cleanup. Do not call while other threads are publishing to this ring.

Trait Implementations

impl Debug for Ring

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

Formats the value using the given formatter.

impl RingFrameSource for Ring

fn kind(&self) -> u8

The OrbitTyped::KIND carried by this ring.

fn head(&self) -> u64

Monotonic visible head. Depending on topology, this counts counters reserved by writers or frames committed by writers.

fn capacity(&self) -> usize

Fixed slot count for this ring.

fn read_at(&self, counter: u64) -> Option<Frame>

Read the frame currently occupying counter % capacity.

fn read_state_at(&self, counter: u64) -> RingRead

Classify the logical counter currently addressed by counter % capacity.