bornera-core 0.0.1-rc.4

Deterministic sans-I/O connection policy for native protocol clients.
Documentation
//! Immutable admission, slice, progress, and discard observations.

use calandria::RetainedBytes;

use crate::{ConnectionEpoch, Delivery, EffectId, FrameMeasure, OperationId};

use super::WriteQueue;

/// Whether one progress report crossed the conservative delivery boundary.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum WriteBoundary {
    /// The operation had already crossed or no byte progressed.
    Unchanged,
    /// The first positive byte progress occurred in this report.
    Crossed,
}

/// Borrowed bytes from only the FIFO queue front.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct WriteSlice<'a> {
    /// Owning epoch.
    pub epoch: ConnectionEpoch,
    /// Owning operation.
    pub operation: OperationId,
    /// Write effect required by the corresponding progress report.
    pub effect: EffectId,
    /// Next contiguous bytes, capped by the caller's requested size.
    pub bytes: &'a [u8],
}

/// Result of applying exact progress to the FIFO front.
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) enum WriteProgress<F> {
    /// The same frame remains at the FIFO front.
    Pending {
        /// Owning operation.
        operation: OperationId,
        /// Whether this report crossed the delivery boundary.
        boundary: WriteBoundary,
    },
    /// The complete frame left write ownership.
    Complete {
        /// Owning operation.
        operation: OperationId,
        /// Owning effect.
        effect: EffectId,
        /// Original complete frame.
        frame: F,
        /// Commit-time wire and retained-memory measurement.
        measure: FrameMeasure,
        /// Whether this report crossed the delivery boundary.
        boundary: WriteBoundary,
        /// Current conservative delivery certainty.
        delivery: Delivery,
    },
}

/// One frame removed before normal write completion.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct DiscardedWrite<F> {
    /// Owning operation.
    pub operation: OperationId,
    /// Owning effect.
    pub effect: EffectId,
    /// Original complete frame.
    pub frame: F,
    /// Wire and retained-memory measurement captured at commit.
    pub measure: FrameMeasure,
    /// Exact bytes that had progressed before removal.
    pub written: usize,
    /// Conservative delivery certainty at removal.
    pub delivery: Delivery,
}

/// Bounded frames removed together when an epoch closes.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct DiscardedWrites<F> {
    pub(crate) writes: Vec<DiscardedWrite<F>>,
    pub(crate) retained_bytes: RetainedBytes,
}

impl<F> DiscardedWrites<F> {
    /// Returns discarded writes in original wire order.
    pub fn writes(&self) -> &[DiscardedWrite<F>] {
        &self.writes
    }

    /// Returns variable memory released by the discarded frames.
    pub const fn retained_bytes(&self) -> RetainedBytes {
        self.retained_bytes
    }

    /// Recovers discarded frames in original wire order.
    pub fn into_writes(self) -> Vec<DiscardedWrite<F>> {
        self.writes
    }
}

impl<F> WriteQueue<F> {
    pub(crate) fn front_is_empty(&self) -> bool {
        self.frames
            .front()
            .is_some_and(|frame| frame.measure.wire_bytes() == 0)
    }
}