Skip to main content

qubit_state_machine/standard/
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::fmt::Debug;
13
14use thiserror::Error;
15
16/// Error returned when an event cannot be applied to the current state.
17///
18/// `S` is the state type and `E` is the event type.
19#[derive(Debug, Clone, Copy, Eq, PartialEq, Error)]
20pub enum StateMachineError<S, E>
21where
22    S: Debug,
23    E: Debug,
24{
25    /// The current state is not registered in the state machine.
26    #[error("unknown state: {state:?}")]
27    UnknownState {
28        /// The unregistered current state.
29        state: S,
30    },
31    /// There is no transition for the current state and event pair.
32    #[error("unknown transition: {source_state:?} --{event:?}--> ?")]
33    UnknownTransition {
34        /// The current source state.
35        source_state: S,
36        /// The event that was triggered.
37        event: E,
38    },
39    /// CAS retry limits were exhausted before a transition could be installed.
40    #[error("CAS transition failed after {attempts} attempt(s)")]
41    CasConflict {
42        /// Number of attempts executed by the CAS executor.
43        attempts: u32,
44    },
45}
46
47/// Result returned by event-triggering state machine operations.
48///
49/// `S` is the state type and `E` is the event type.
50pub type StateMachineResult<S, E> = Result<S, StateMachineError<S, E>>;