qubit_state_machine/
state_machine_error.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! Runtime errors returned by state transitions.
11
12use std::error::Error;
13use std::fmt::{
14    self,
15    Debug,
16    Display,
17    Formatter,
18};
19
20/// Error returned when an event cannot be applied to the current state.
21///
22/// `S` is the state type and `E` is the event type.
23#[derive(Debug, Clone, Copy, Eq, PartialEq)]
24pub enum StateMachineError<S, E> {
25    /// The current state is not registered in the state machine.
26    UnknownState {
27        /// The unregistered current state.
28        state: S,
29    },
30    /// There is no transition for the current state and event pair.
31    UnknownTransition {
32        /// The current source state.
33        source: S,
34        /// The event that was triggered.
35        event: E,
36    },
37    /// CAS retry limits were exhausted before a transition could be installed.
38    CasConflict {
39        /// Number of attempts executed by the CAS executor.
40        attempts: u32,
41    },
42}
43
44/// Result returned by event-triggering state machine operations.
45///
46/// `S` is the state type and `E` is the event type.
47pub type StateMachineResult<S, E> = Result<S, StateMachineError<S, E>>;
48
49impl<S, E> Display for StateMachineError<S, E>
50where
51    S: Debug,
52    E: Debug,
53{
54    /// Formats the transition failure with enough context for diagnostics.
55    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
56        match self {
57            Self::UnknownState { state } => {
58                write!(formatter, "unknown state: {state:?}")
59            }
60            Self::UnknownTransition { source, event } => {
61                write!(formatter, "unknown transition: {source:?} --{event:?}--> ?")
62            }
63            Self::CasConflict { attempts } => {
64                write!(
65                    formatter,
66                    "CAS transition failed after {attempts} attempt(s)"
67                )
68            }
69        }
70    }
71}
72
73impl<S, E> Error for StateMachineError<S, E>
74where
75    S: Debug,
76    E: Debug,
77{
78}
qubit_state_machine/state_machine_error.rs

qubit_state_machine/
state_machine_error.rs
