byteor_pipeline_kernel/

lane.rs

//! Lane traits.

/// TX error that keeps "full" distinct from other failures.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum LaneTxError {
    /// The lane is full.
    Full,
    /// The payload length exceeds the maximum slot size.
    TooLarge {
        /// Maximum supported payload size in bytes.
        max: usize,
        /// Actual payload size in bytes.
        len: usize,
    },
    /// Any other TX failure.
    Failed,
}

/// RX error for borrowed receive APIs.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum LaneRxError {
    /// Any RX failure (layout/incompatibility/etc).
    Failed,
}

/// Slot handle returned by [`LaneRxSlot`].
///
/// Slot passing requires that a slot can be inspected without copying bytes.
pub trait LaneSlot {
    /// Borrow the payload bytes.
    fn as_bytes(&self) -> &[u8];
}

impl LaneSlot for indexbus_core::EventsSlot {
    #[inline]
    fn as_bytes(&self) -> &[u8] {
        indexbus_core::EventsSlot::as_bytes(self)
    }
}

/// RX side of a lane.
pub trait LaneRx {
    /// Receive one message into `buf`, returning the number of bytes written.
    fn recv(&mut self, buf: &mut [u8]) -> Option<usize>;
}

/// RX side of a lane, borrowed receive.
///
/// This enables adapters to parse/decode without copying bytes into an intermediate buffer.
///
/// The borrowed `&[u8]` passed to the callback is only valid for the duration of the callback.
pub trait LaneRxBorrow {
    /// Receive one message and pass it to `f` by borrowed slice.
    fn recv_with<F, R>(&mut self, f: F) -> core::result::Result<Option<R>, LaneRxError>
    where
        F: FnOnce(&[u8]) -> R;
}

/// RX side of a lane, owned slot receive.
///
/// This enables *slot passing*: receiving an owned slot handle (slot index) that can be forwarded
/// to a compatible TX without copying payload bytes.
pub trait LaneRxSlot {
    /// Slot handle type.
    type Slot: LaneSlot;

    /// Receive one message as an owned slot.
    fn try_recv_slot(&mut self) -> core::result::Result<Option<Self::Slot>, LaneRxError>;
}

/// RX side of a lane, batch slot receive.
///
/// This is a convenience API for draining up to `max` slots with a single call, allowing a lane
/// backing to provide a more efficient implementation than looping `try_recv_slot` in the caller.
///
/// The default implementation repeatedly calls [`LaneRxSlot::try_recv_slot`].
pub trait LaneRxSlotBatch: LaneRxSlot {
    /// Receive and process up to `max` slots.
    ///
    /// Calls `f` once per slot. If `f` returns `false`, the drain stops early.
    ///
    /// Returns the number of slots received (and passed to `f`).
    fn try_recv_slots<F>(
        &mut self,
        max: usize,
        mut f: F,
    ) -> core::result::Result<usize, LaneRxError>
    where
        F: FnMut(Self::Slot) -> bool,
    {
        let max = max.max(1);
        let mut n = 0;

        for _ in 0..max {
            let Some(slot) = self.try_recv_slot()? else {
                break;
            };
            n += 1;
            if !f(slot) {
                break;
            }
        }

        Ok(n)
    }
}

impl<T> LaneRxSlotBatch for T where T: LaneRxSlot {}

/// TX side of a lane.
pub trait LaneTx {
    /// Publish the message.
    fn publish(&mut self, msg: &[u8]) -> core::result::Result<(), LaneTxError>;
}

/// TX side of a lane, slot-write publish.
///
/// This enables adapters to write directly into the backing slot buffer, avoiding an
/// intermediate copy.
pub trait LaneTxWith {
    /// Publish a message by writing it into a provided slot buffer.
    ///
    /// The closure returns the number of bytes written.
    fn publish_with<F>(&mut self, f: F) -> core::result::Result<(), LaneTxError>
    where
        F: FnOnce(&mut [u8]) -> usize;
}

/// Error returned by fallible slot-write publish APIs.
///
/// This distinguishes:
/// - backpressure (`Full`)
/// - backing failures (`Failed`)
/// - user-provided encoder failures (`Encode(E)`), which publish nothing.
#[derive(Debug, PartialEq, Eq)]
pub enum LaneTxWithError<E> {
    /// The lane is full.
    Full,
    /// Any other TX failure.
    Failed,
    /// The user-provided encoder returned an error.
    ///
    /// No message is published when this occurs.
    Encode(E),
}

impl<E> From<LaneTxError> for LaneTxWithError<E> {
    #[inline]
    fn from(value: LaneTxError) -> Self {
        match value {
            LaneTxError::Full => Self::Full,
            LaneTxError::TooLarge { .. } | LaneTxError::Failed => Self::Failed,
        }
    }
}

/// TX side of a lane, slot-write publish with a fallible encoder.
///
/// This enables adapters/stages to write directly into the backing slot buffer and return an
/// error without publishing.
pub trait LaneTxWithResult {
    /// Publish a message by writing it into a provided slot buffer.
    ///
    /// The closure returns the number of bytes written, or an error.
    fn publish_with_result<F, E>(&mut self, f: F) -> core::result::Result<(), LaneTxWithError<E>>
    where
        F: FnOnce(&mut [u8]) -> core::result::Result<usize, E>;
}

/// Error returned when publishing an owned slot.
///
/// The slot is returned to the caller so it can be retried (`Full`) or dropped.
#[derive(Debug, PartialEq, Eq)]
pub enum LaneTxSlotError<S> {
    /// The lane is full; the caller can retry.
    Full(S),
    /// Slot is incompatible with the lane backing; caller may fall back to copying.
    Incompatible(S),
    /// Any other failure.
    Failed(S),
}

/// TX side of a lane, slot-forward publish.
///
/// Unlike [`LaneTx::publish`], this publishes by transferring ownership of a previously received
/// slot (slot index) into a compatible queue.
pub trait LaneTxSlot<S> {
    /// Publish an owned slot.
    fn publish_slot(&mut self, slot: S) -> core::result::Result<(), LaneTxSlotError<S>>;
}