indexbus_core/
errors.rs

1/// Core error type returned by the low-level region handles.
2///
3/// This error type is intentionally small and `no_std`-friendly.
4///
5/// ## Recovery guidance
6///
7/// - Capacity errors ([`Error::Full`]/[`Error::Empty`]) are typically recoverable by retrying
8///   after progress in another component (draining, routing, or polling).
9/// - Layout errors ([`Error::NotInitialized`]/[`Error::IncompatibleLayout`]) are configuration or
10///   initialization problems and usually require re-initialization or a compatible mapping.
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub enum Error {
13    /// The mapped layout exists but has not completed initialization.
14    ///
15    /// This commonly means the region creator has not called an `init_*` routine yet, or another
16    /// process is still in the middle of initializing.
17    NotInitialized,
18    /// The mapped layout is initialized but incompatible with this ABI version, capabilities, or
19    /// structural expectations.
20    ///
21    /// Typical causes:
22    /// - wrong region type at the address
23    /// - option mismatch (e.g., blocking wake section expected but not present)
24    /// - corrupted or partially initialized mapping
25    IncompatibleLayout,
26    /// The operation could not proceed because the region is full.
27    ///
28    /// This is a backpressure signal. Callers may retry after consumers make progress.
29    Full,
30    /// The operation could not proceed because the region is empty.
31    ///
32    /// This is not exceptional; polling receivers often treat this as `Ok(None)` at higher levels.
33    Empty,
34    /// The payload length exceeds the maximum slot size.
35    ///
36    /// The maximum is fixed by the ABI layout constant [`crate::INDEXBUS_SLOT_DATA_SIZE`].
37    TooLarge {
38        /// Maximum supported payload size in bytes.
39        max: usize,
40        /// Actual payload size in bytes.
41        len: usize,
42    },
43    /// The provided output buffer is too small to hold the message/state.
44    ///
45    /// Callers should retry with a larger buffer of at least `required` bytes.
46    BufferTooSmall {
47        /// Required buffer size in bytes.
48        required: usize,
49        /// Provided buffer size in bytes.
50        provided: usize,
51    },
52}
53
54/// Error returned by `publish_with` APIs.
55#[derive(Debug, Clone, PartialEq, Eq)]
56pub enum PublishWithError<E> {
57    /// A core error (full, too large, incompatible layout, etc.).
58    Core(Error),
59    /// The user-provided encoder returned an error.
60    ///
61    /// No message is published when this occurs.
62    Encode(E),
63}
64
65impl<E> From<Error> for PublishWithError<E> {
66    fn from(value: Error) -> Self {
67        Self::Core(value)
68    }
69}
70
71/// Error returned by `try_recv_with` APIs.
72#[derive(Debug, Clone, PartialEq, Eq)]
73pub enum RecvWithError<E> {
74    /// A core error (incompatible layout, etc.).
75    Core(Error),
76    /// The user-provided decoder returned an error.
77    ///
78    /// The message is considered consumed; higher-level retry should be implemented by the
79    /// caller (e.g., by re-publishing) if desired.
80    Decode(E),
81}
82
83impl<E> From<Error> for RecvWithError<E> {
84    fn from(value: Error) -> Self {
85        Self::Core(value)
86    }
87}
indexbus_core/errors.rs

indexbus_core/
errors.rs
