qubit_state_machine/fast/fast_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
11//! Runtime errors returned by `FastStateMachine` transitions.
12
13use qubit_cas::FastCasError;
14use thiserror::Error;
15
16/// Error returned when applying an event through a [`crate::FastStateMachine`].
17#[derive(Debug, Clone, Copy, Eq, PartialEq, Error)]
18pub enum FastStateMachineError {
19 /// The current state code is not configured in the state machine.
20 #[error("unknown state: {state}")]
21 UnknownState {
22 /// The unregistered current state code.
23 state: usize,
24 },
25
26 /// No transition is configured for the `(state, event)` pair.
27 #[error("unknown transition: {source_state} --{event}--> ?")]
28 UnknownTransition {
29 /// The source state code.
30 source_state: usize,
31
32 /// The triggering event code.
33 event: usize,
34 },
35
36 /// CAS conflicts were exhausted before the update could be installed.
37 #[error("CAS transition failed after {attempts} attempt(s)")]
38 CasConflict {
39 /// The total number of CAS attempts executed.
40 attempts: u32,
41 },
42}
43
44/// Result returned by `FastStateMachine` runtime transition APIs.
45pub type FastStateMachineResult = Result<usize, FastStateMachineError>;
46
47/// Converts a compact CAS error into the runtime error used by fast state machines.
48#[doc(hidden)]
49pub fn fast_state_machine_error_from_fast_cas_error(
50 error: FastCasError<FastStateMachineError>,
51) -> FastStateMachineError {
52 match error {
53 FastCasError::Abort { error, .. } => error,
54 FastCasError::Conflict { attempts, .. } => FastStateMachineError::CasConflict { attempts },
55 }
56}