pub struct Fleet { /* private fields */ }Expand description
Per-process handle into the fleet. Cheap to clone — the inner
state is Arc-shared.
Implementations§
Source§impl Fleet
impl Fleet
Sourcepub fn cursor_at_head<T: OrbitTyped>(&self) -> RingCursor
pub fn cursor_at_head<T: OrbitTyped>(&self) -> RingCursor
Cursor that starts after the latest frame currently published for
T. Useful for subscribers that only want future frames.
Sourcepub const fn cursor_from_start<T: OrbitTyped>(&self) -> RingCursor
pub const fn cursor_from_start<T: OrbitTyped>(&self) -> RingCursor
Cursor that starts at counter 0 for T.
Sourcepub fn poll_ring<T: OrbitTyped>(&self, cursor: &mut RingCursor) -> RingPoll
pub fn poll_ring<T: OrbitTyped>(&self, cursor: &mut RingCursor) -> RingPoll
Walk cursor over the ring for T, advancing it to the current
head and reporting skipped counters as crate::ring::cursor::RingLoss.
Source§impl Fleet
impl Fleet
Sourcepub fn join(name: &'static str, fleet_size: u8) -> Result<Self>
pub fn join(name: &'static str, fleet_size: u8) -> Result<Self>
Join (or create) a fleet under name with fleet_size total
expected members. In V0 every call returns a fresh local
fleet; the backing slot table is process-local.
Sourcepub fn join_as(
name: &'static str,
fleet_size: u8,
node_id: NodeId,
) -> Result<Self>
pub fn join_as( name: &'static str, fleet_size: u8, node_id: NodeId, ) -> Result<Self>
Join (or create) a process-local fleet with an explicit node id.
Sourcepub fn join_shm(
name: &'static str,
fleet_size: u8,
capacity: usize,
) -> Result<Self>
pub fn join_shm( name: &'static str, fleet_size: u8, capacity: usize, ) -> Result<Self>
Join (or create) a fleet whose ring storage is backed by
POSIX shared memory. Multiple processes calling this with
the same name and capacity share the same kernel-level
segments — the fleet sees each other’s writes.
capacity must be a power of two (cheap modulo); applies
per-KIND ring (each OrbitTyped kind gets its own SHM
segment of capacity slots).
Cross-process naming: segments are /orbit-{name}-{kind}-{uid}.
macOS limits POSIX SHM names to 31 chars (PSHMNAMLEN); a
short fleet name is required there.
Sourcepub fn join_shm_as(
name: &'static str,
fleet_size: u8,
capacity: usize,
node_id: NodeId,
) -> Result<Self>
pub fn join_shm_as( name: &'static str, fleet_size: u8, capacity: usize, node_id: NodeId, ) -> Result<Self>
Join (or create) a SHM-backed fleet with an explicit node id.
pub fn name(&self) -> &'static str
pub fn fleet_size(&self) -> u8
pub fn node_id(&self) -> NodeId
Sourcepub fn next_id<T: OrbitTyped>(&self) -> NetId64
pub fn next_id<T: OrbitTyped>(&self) -> NetId64
Mint a fresh fleet-unique NetId64 for type T without
publishing anything. Use this when the caller only needs the
id (e.g. minting an id to attach to data being persisted to
DB before going through the ring).
For most use cases prefer Fleet::publish — it mints AND
stores in a single atomic step.
Sourcepub fn is_shm(&self) -> bool
pub fn is_shm(&self) -> bool
True when this fleet’s ring storage is backed by POSIX SHM (visible across processes). False for in-memory fleets.
Sourcepub fn ring<T: OrbitTyped>(&self) -> Arc<Ring>
pub fn ring<T: OrbitTyped>(&self) -> Arc<Ring>
Get-or-create the in-memory ring for type T. Only valid
for fleets created via Fleet::join; SHM-backed fleets
should use Fleet::shm_ring instead.
§Panics
Panics if called on a SHM-backed fleet.
Sourcepub fn ring_with_capacity<T: OrbitTyped>(&self, capacity: usize) -> Arc<Ring>
pub fn ring_with_capacity<T: OrbitTyped>(&self, capacity: usize) -> Arc<Ring>
Get-or-create the in-memory ring for type T with an
explicit capacity. See Fleet::ring.
Sourcepub fn shm_ring<T: OrbitTyped>(&self) -> Result<Arc<ShmRing>>
pub fn shm_ring<T: OrbitTyped>(&self) -> Result<Arc<ShmRing>>
Get-or-create the SHM ring for type T. Only valid on fleets
created via Fleet::join_shm.
§Errors
Returns an io::Error if the SHM segment cannot be opened
(permissions, name too long, etc.).
§Panics
Panics if called on an in-memory fleet.
Sourcepub fn publish<T: OrbitTyped>(
&self,
frame_kind: u8,
ver: u64,
payload: Bytes,
) -> NetId64
pub fn publish<T: OrbitTyped>( &self, frame_kind: u8, ver: u64, payload: Bytes, ) -> NetId64
Publish a payload to the ring for type T. Mints a
NetId64 (atomic with slot reservation), writes the
Frame to the appropriate ring (in-memory or SHM), and
returns the id.
§Panics
On a SHM-backed fleet, panics if the SHM open fails or the
payload exceeds [ring_shm::PAYLOAD_MAX]. V1 contract: SHM
errors are operator-visible failures, not silent ones.
Sourcepub fn read(&self, id: NetId64) -> Option<Frame>
pub fn read(&self, id: NetId64) -> Option<Frame>
Look up a previously-published frame by its id. Returns the frame if its slot still holds the same id (i.e. the ring has not wrapped past it).
Sourcepub fn read_head<T: OrbitTyped>(&self) -> Option<Frame>
pub fn read_head<T: OrbitTyped>(&self) -> Option<Frame>
Read the most recent frame for type T (head - 1 in the ring).
Returns None if no write has happened yet.
Sourcepub fn head<T: OrbitTyped>(&self) -> u64
pub fn head<T: OrbitTyped>(&self) -> u64
Current head (write position) for type T’s ring. Lazily
creates / attaches the ring on first access — important for
cross-process readers, where a child process may need to
attach to a SHM segment a peer already populated. Returns 0
when the ring is fresh / no writes have happened.
Sourcepub fn read_at<T: OrbitTyped>(&self, counter: u64) -> Option<Frame>
pub fn read_at<T: OrbitTyped>(&self, counter: u64) -> Option<Frame>
Read whatever frame currently occupies the slot at
counter % capacity for type T’s ring. Lazily attaches
the ring on first access (same rationale as Fleet::head).
Returns None if the slot is empty/torn or attach fails.
Used by walking readers; for typed handle-based reads,
prefer Fleet::read.
Sourcepub fn ring_capacity<T: OrbitTyped>(&self) -> usize
pub fn ring_capacity<T: OrbitTyped>(&self) -> usize
Capacity of the ring for type T. Lazily attaches the ring
on first access. Falls back to DEFAULT_RING_CAPACITY when
SHM attach fails.
Sourcepub fn reset_ring<T: OrbitTyped>(&self) -> Result<()>
pub fn reset_ring<T: OrbitTyped>(&self) -> Result<()>
Clear the ring for T and reset its write head to zero.
This is an owner-side boot cleanup primitive. It is safe for runtime state such as events and periodic metrics when the embedding application calls it before peer processes begin publishing. It is not a coordination protocol; callers must not reset a ring while other fleet members are actively writing it.
Sourcepub fn publish_heartbeat(&self) -> FleetHeartbeat
pub fn publish_heartbeat(&self) -> FleetHeartbeat
Publish a fleet-level Orbit heartbeat for this node.
This is substrate liveness, not process supervision. Embedders may inspect it to see whether a node is still writing into the Orbit fabric, but worker kill/restart policy belongs above this crate.