orbit-link 0.6.8

Named reusable duplex sessions between members of an Orbit fleet.
Documentation
//! Duplex byte flow attached to an inbox frame.
//!
//! One stream slot carries both directions. The originator creates side A and
//! encodes the ticket in its application-defined inbox frame; the target opens
//! side B. A retained creator endpoint can be rearmed after side B releases
//! it, then announced in another frame to any target lane.

use std::sync::Arc;

use orbit_core::{Fleet, NodeId};
use orbit_stream::{Endpoint, Incarnation, Streams, Ticket};

use super::{LinkSpec, Reclaimed, Result};

/// This process's handle on a named link fleet's stream table.
pub struct LinkBodies {
    streams: Streams,
}

impl LinkBodies {
    pub fn open(
        fleet: Arc<Fleet>,
        incarnation: u64,
        spec: LinkSpec,
    ) -> Result<Self> {
        spec.validate()?;
        if fleet.fleet_capacity() != spec.fleet_capacity {
            return Err(super::Error::Malformed(
                "link stream fleet capacity differs from its inbox specification",
            ));
        }
        let streams = Streams::with_spec(
            fleet,
            Incarnation::new(incarnation),
            spec.streams,
        )?;
        Ok(Self { streams })
    }

    /// Join the stream table under the same fleet name and lane index as the
    /// inbox participant.
    #[cfg(unix)]
    pub fn for_name(
        name: &str,
        lane_index: usize,
        incarnation: u64,
        spec: LinkSpec,
    ) -> Result<Self> {
        super::check_name(name, spec)?;
        if lane_index >= spec.fleet_capacity as usize {
            return Err(super::Error::Malformed(
                "link lane is outside the fleet capacity",
            ));
        }
        let fleet = Fleet::join_shm_as(
            name,
            spec.fleet_capacity,
            NodeId::new(lane_index as u16),
        )?;
        Self::open(Arc::new(fleet), incarnation, spec)
    }

    /// Body transport for a dedicated cross-user Link. No shared event rings
    /// or fleet membership resources are opened by this constructor.
    #[cfg(unix)]
    pub fn for_group(
        name: &str,
        lane_index: usize,
        incarnation: u64,
        spec: LinkSpec,
        access: orbit_core::shm::GroupAccess,
    ) -> Result<Self> {
        spec.validate()?;
        if lane_index >= usize::from(spec.fleet_capacity) {
            return Err(super::Error::Malformed(
                "link lane is outside the fleet capacity",
            ));
        }
        Ok(Self {
            streams: Streams::with_group(
                name,
                spec.fleet_capacity,
                NodeId::new(lane_index as u16),
                Incarnation::new(incarnation),
                spec.streams,
                access,
            )?,
        })
    }

    /// Create side A and the ticket an inbox frame carries to side B.
    pub fn create(&self) -> Result<(Endpoint, Ticket)> {
        Ok(self.streams.create()?)
    }

    /// Clear shared state for a retained creator endpoint and restore its
    /// local writer after an earlier FIN.
    pub fn rearm_endpoint(
        &self,
        endpoint: &mut Endpoint,
    ) -> Result<()> {
        endpoint.rearm(&self.streams)?;
        Ok(())
    }

    /// Clear only the shared slot state.
    ///
    /// Prefer [`LinkBodies::rearm_endpoint`] when the retained endpoint sent
    /// FIN: a `WriteHalf` remembers FIN process-locally and must be restored
    /// together with the SHM directions.
    pub fn rearm_ticket(
        &self,
        ticket: &Ticket,
    ) -> Result<()> {
        self.streams.rearm(ticket.id)?;
        Ok(())
    }

    pub fn accept(
        &self,
        ticket: Ticket,
    ) -> Result<Endpoint> {
        Ok(self.streams.open(ticket)?)
    }

    pub fn is_live(
        &self,
        ticket: &Ticket,
    ) -> bool {
        self.streams.is_live(ticket.id)
    }

    pub fn node_died(
        &self,
        node: NodeId,
        incarnation: u64,
    ) {
        self.streams.node_dead(node, Incarnation::new(incarnation));
    }

    pub fn reclaim(
        &self,
        lanes: &[Reclaimed],
    ) {
        for lane in lanes {
            self.node_died(NodeId::new(lane.lane as u16), lane.incarnation);
        }
    }

    pub fn streams(&self) -> &Streams {
        &self.streams
    }

    #[cfg(unix)]
    pub fn unlink(&self) -> Result<()> {
        self.streams.unlink()?;
        Ok(())
    }
}