Skip to main content

bornera_core/admission/
error.rs

1//! Admission and commit failures that preserve pre-publication ownership.
2
3use core::fmt;
4
5use crate::{Delivery, WriteAdmissionFailure};
6
7use super::OperationPermit;
8
9/// Why an operation reservation was rejected.
10#[derive(Clone, Copy, Debug, Eq, PartialEq)]
11#[non_exhaustive]
12pub enum ReserveError {
13    /// The connection is not accepting this class of work.
14    AdmissionClosed,
15    /// The absolute deadline is already due.
16    DeadlineElapsed,
17    /// The accepted-operation count is full.
18    OperationCapacity,
19    /// Semantic retained-byte capacity is full.
20    RetainedByteCapacity,
21    /// Write-frame count or retained-memory capacity is full.
22    WriteCapacity,
23    /// No match key is currently available.
24    MatchKeyExhausted,
25    /// A generated fixed-width identity is exhausted.
26    IdentityExhausted,
27    /// A prior invariant failure poisoned this fixed-epoch owner.
28    OwnerPoisoned,
29}
30
31impl fmt::Display for ReserveError {
32    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
33        formatter.write_str(match self {
34            Self::AdmissionClosed => "connection admission is closed",
35            Self::DeadlineElapsed => "operation deadline is already elapsed",
36            Self::OperationCapacity => "operation count capacity is exhausted",
37            Self::RetainedByteCapacity => "retained byte capacity is exhausted",
38            Self::WriteCapacity => "write-frame count or retained-memory capacity is exhausted",
39            Self::MatchKeyExhausted => "match key space is exhausted",
40            Self::IdentityExhausted => "operation or effect identity is exhausted",
41            Self::OwnerPoisoned => "connection owner is poisoned",
42        })
43    }
44}
45
46impl core::error::Error for ReserveError {}
47
48/// Why a reserved operation could not be committed.
49#[derive(Clone, Copy, Debug, Eq, PartialEq)]
50#[non_exhaustive]
51pub enum CommitErrorKind {
52    /// The permit belongs to another machine or epoch.
53    ForeignPermit,
54    /// Admission closed after reservation and before commit.
55    AdmissionClosed,
56    /// The frame's cached retained footprint exceeds its reserved write-memory capacity.
57    FrameTooLarge,
58    /// A prior invariant failure poisoned this fixed-epoch owner.
59    OwnerPoisoned,
60}
61
62/// Why an atomic frame commit could not transfer ownership to the writer.
63#[derive(Clone, Copy, Debug, Eq, PartialEq)]
64#[non_exhaustive]
65pub enum FrameCommitFailure {
66    /// Connection policy rejected the still-affine permit.
67    Policy(CommitErrorKind),
68    /// The bounded write owner rejected the complete frame.
69    Writer(WriteAdmissionFailure),
70}
71
72/// Failed atomic commit preserving both the permit and exact unsent frame.
73pub struct FrameCommitError<F> {
74    failure: FrameCommitFailure,
75    permit: OperationPermit,
76    frame: F,
77}
78
79impl<F> FrameCommitError<F> {
80    pub(crate) const fn new(
81        failure: FrameCommitFailure,
82        permit: OperationPermit,
83        frame: F,
84    ) -> Self {
85        Self {
86            failure,
87            permit,
88            frame,
89        }
90    }
91
92    /// Returns the mechanical rejection reason.
93    pub const fn failure(&self) -> FrameCommitFailure {
94        self.failure
95    }
96
97    /// Returns certainty for a frame never accepted by the writer.
98    pub const fn delivery(&self) -> Delivery {
99        Delivery::NotSent
100    }
101
102    /// Recovers the still-affine permit and exact unadmitted frame.
103    pub fn into_parts(self) -> (OperationPermit, F) {
104        (self.permit, self.frame)
105    }
106}
107
108impl<F> fmt::Debug for FrameCommitError<F>
109where
110    F: fmt::Debug,
111{
112    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
113        formatter
114            .debug_struct("FrameCommitError")
115            .field("failure", &self.failure)
116            .field("permit", &self.permit)
117            .field("frame", &self.frame)
118            .finish()
119    }
120}
121
122impl<F> fmt::Display for FrameCommitError<F> {
123    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
124        self.failure.fmt(formatter)
125    }
126}
127
128impl<F: fmt::Debug> core::error::Error for FrameCommitError<F> {}
129
130impl fmt::Display for FrameCommitFailure {
131    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
132        match self {
133            Self::Policy(kind) => formatter.write_str(match kind {
134                CommitErrorKind::ForeignPermit => "operation permit belongs to another epoch",
135                CommitErrorKind::AdmissionClosed => "admission closed before operation commit",
136                CommitErrorKind::FrameTooLarge => {
137                    "frame retained footprint exceeds reserved write memory"
138                }
139                CommitErrorKind::OwnerPoisoned => "connection owner is poisoned",
140            }),
141            Self::Writer(failure) => failure.fmt(formatter),
142        }
143    }
144}