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 every counter currently claimed for T.
Useful for subscribers that only want future writes.
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 toward the current claim head for T, stopping at
an in-flight counter and reporting definitive losses as
crate::ring::cursor::RingLoss.
Sourcepub fn lane_cursor_at_head<T: OrbitTyped>(&self) -> FleetLaneCursor
pub fn lane_cursor_at_head<T: OrbitTyped>(&self) -> FleetLaneCursor
Create one caller-owned cursor per physical node lane, starting at each lane’s current head.
Sourcepub fn lane_cursor_from_start<T: OrbitTyped>(&self) -> FleetLaneCursor
pub fn lane_cursor_from_start<T: OrbitTyped>(&self) -> FleetLaneCursor
Create one caller-owned cursor per physical node lane, starting at counter zero.
Sourcepub fn poll_lanes<T: OrbitTyped>(
&self,
cursor: &mut FleetLaneCursor,
) -> FleetLanePoll
pub fn poll_lanes<T: OrbitTyped>( &self, cursor: &mut FleetLaneCursor, ) -> FleetLanePoll
Poll every physical node lane and combine the retained frames and loss
counters into one result. Frames retain their writer node in id;
callers that need semantic ordering across lanes must provide it.
Source§impl Fleet
impl Fleet
Sourcepub fn join(name: &'static str, fleet_capacity: u16) -> Result<Self>
pub fn join(name: &'static str, fleet_capacity: u16) -> Result<Self>
Join (or create) a fleet under name with fleet_capacity physical
node lanes. In-memory backings remain process-local.
Sourcepub fn join_as(
name: &'static str,
fleet_capacity: u16,
node_id: NodeId,
) -> Result<Self>
pub fn join_as( name: &'static str, fleet_capacity: u16, 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_capacity: u16) -> Result<Self>
pub fn join_shm(name: &'static str, fleet_capacity: u16) -> Result<Self>
Join (or create) a fleet whose ring storage is backed by
POSIX shared memory. Multiple processes calling this with
the same name share the same kernel-level
segments — the fleet sees each other’s writes.
Each OrbitTyped kind gets its own SHM segment whose layout is
declared by OrbitTyped::RING_SPEC.
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_capacity: u16,
node_id: NodeId,
) -> Result<Self>
pub fn join_shm_as( name: &'static str, fleet_capacity: u16, node_id: NodeId, ) -> Result<Self>
Join (or create) a SHM-backed fleet with an explicit node id.
Per-node rings require one active process membership per node id. Orbit validates the id range but does not own process lifecycle and therefore cannot prevent duplicate live memberships.
pub fn name(&self) -> &'static str
Sourcepub fn fleet_capacity(&self) -> u16
pub fn fleet_capacity(&self) -> u16
Number of physical node lanes reserved for this fleet.
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 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_batch<T: OrbitTyped>(
&self,
frame_kind: u8,
ver: u64,
payloads: Vec<Bytes>,
) -> Vec<NetId64>
pub fn publish_batch<T: OrbitTyped>( &self, frame_kind: u8, ver: u64, payloads: Vec<Bytes>, ) -> Vec<NetId64>
Publish a contiguous batch into one ring lane.
The returned ids are ordered and consecutive. For per-node rings the lane head becomes visible only after every frame in the batch has been committed. Semantic layers can use this to publish a multi-slot blob, then publish a separate descriptor that references the first id and frame count.
§Panics
Panics if the ring cannot be opened, a payload exceeds the declared slot capacity, or the batch itself is larger than the ring.
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. Per-node rings read this
fleet handle’s local lane; shared rings read their sole lane.
Sourcepub fn head<T: OrbitTyped>(&self) -> u64
pub fn head<T: OrbitTyped>(&self) -> u64
Current head for type T’s ring. Per-node rings report this fleet
handle’s local committed head; shared rings report their sole lane’s
visible head.
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 counters have been claimed.
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 counter % capacity.
Per-node rings read this fleet handle’s local lane. 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 lane_head<T: OrbitTyped>(&self, node_id: NodeId) -> u64
pub fn lane_head<T: OrbitTyped>(&self, node_id: NodeId) -> u64
Current head for one physical node lane.
On a shared ring every node id addresses the sole shared lane.
Sourcepub fn read_lane_at<T: OrbitTyped>(
&self,
node_id: NodeId,
counter: u64,
) -> Option<Frame>
pub fn read_lane_at<T: OrbitTyped>( &self, node_id: NodeId, counter: u64, ) -> Option<Frame>
Read the frame currently occupying one node lane’s counter slot.
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 T::RING_SPEC.capacity when
SHM attach fails.
Sourcepub fn next_ring_version<T: OrbitTyped>(&self) -> u64
pub fn next_ring_version<T: OrbitTyped>(&self) -> u64
Allocate one semantic version shared by every writer lane of T.
This is separate from each lane’s physical frame counter. It is useful for semantic layers that retain per-node write scalability but require a deterministic fleet-wide last-write-wins order.
Sourcepub fn current_ring_version<T: OrbitTyped>(&self) -> u64
pub fn current_ring_version<T: OrbitTyped>(&self) -> u64
Return the last semantic version allocated for T without advancing it.
Sourcepub fn reset_ring<T: OrbitTyped>(&self) -> Result<()>
pub fn reset_ring<T: OrbitTyped>(&self) -> Result<()>
Clear every lane for T and reset all heads 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 ring_event_fd<T: OrbitTyped>(&self) -> Result<RingEventFd>
pub fn ring_event_fd<T: OrbitTyped>(&self) -> Result<RingEventFd>
Create a process-local readiness fd for one notified SHM ring.
The fd only signals that the ring generation changed. After draining it, callers must poll the ring with their own cursor. Multiple writes may coalesce into one readiness notification.
Sourcepub fn publish_notified<T: OrbitTyped>(
&self,
frame_kind: u8,
ver: u64,
payload: Bytes,
) -> Result<NetId64>
pub fn publish_notified<T: OrbitTyped>( &self, frame_kind: u8, ver: u64, payload: Bytes, ) -> Result<NetId64>
Publish one frame and notify native waiters after it commits.
Sourcepub fn publish_batch_notified<T: OrbitTyped>(
&self,
frame_kind: u8,
ver: u64,
payloads: Vec<Bytes>,
) -> Result<Vec<NetId64>>
pub fn publish_batch_notified<T: OrbitTyped>( &self, frame_kind: u8, ver: u64, payloads: Vec<Bytes>, ) -> Result<Vec<NetId64>>
Publish one contiguous batch and notify native waiters once after the complete batch commits.