1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232
//! A framework for building finite state machines in Rust //! //! The `rust-fsm` crate provides a simple and universal framework for building //! state machines in Rust with minimum effort. //! //! The essential part of this crate is the //! [`StateMachineImpl`](trait.StateMachineImpl.html) trait. This trait allows a //! developer to provide a strict state machine definition, e.g. specify its: //! //! * An input alphabet - a set of entities that the state machine takes as //! inputs and performs state transitions based on them. //! * Possible states - a set of states this machine could be in. //! * An output alphabet - a set of entities that the state machine may output //! as results of its work. //! * A transition function - a function that changes the state of the state //! machine based on its current state and the provided input. //! * An output function - a function that outputs something from the output //! alphabet based on the current state and the provided inputs. //! * The initial state of the machine. //! //! Note that on the implementation level such abstraction allows build any type //! of state machines: //! //! * A classical state machine by providing only an input alphabet, a set of //! states and a transition function. //! * A Mealy machine by providing all entities listed above. //! * A Moore machine by providing an output function that do not depend on the //! provided inputs. //! //! # Usage in `no_std` environments //! //! This library has the feature named `std` which is enabled by default. You //! may want to import this library as //! `rust-fsm = { version = "0.5", default-features = false, features = ["dsl"] }` //! to use it in a `no_std` environment. This only affects error types (the //! `Error` trait is only available in `std`). //! //! The DSL implementation re-export is gated by the feature named `dsl` which //! is also enabled by default. //! //! # Use //! //! Initially this library was designed to build an easy to use DSL for defining //! state machines on top of it. Using the DSL will require to connect an //! additional crate `rust-fsm-dsl` (this is due to limitation of the procedural //! macros system). //! //! ## Using the DSL for defining state machines //! //! The DSL is parsed by the `state_machine` macro. Here is a little example. //! //! ```rust,ignore //! use rust_fsm::*; //! //! state_machine! { //! derive(Debug) //! CircuitBreaker(Closed) //! //! Closed(Unsuccessful) => Open [SetupTimer], //! Open(TimerTriggered) => HalfOpen, //! HalfOpen => { //! Successful => Closed, //! Unsuccessful => Open [SetupTimer] //! } //! } //! ``` //! //! This code sample: //! //! * Defines a state machine called `CircuitBreaker`; //! * Derives the `Debug` trait for it (the `derive` section is optional); //! * Sets the initial state of this state machine to `Closed`; //! * Defines state transitions. For example: on receiving the `Successful` //! input when in the `HalfOpen` state, the machine must move to the `Closed` //! state; //! * Defines outputs. For example: on receiving `Unsuccessful` in the //! `Closed` state, the machine must output `SetupTimer`. //! //! This state machine can be used as follows: //! //! ```rust,ignore //! // Initialize the state machine. The state is `Closed` now. //! let mut machine: StateMachine<CircuitBreaker> = StateMachine::new(); //! // Consume the `Successful` input. No state transition is performed. //! let _ = machine.consume(&CircuitBreakerInput::Successful); //! // Consume the `Unsuccesful` input. The machine is moved to the `Open` //! // state. The output is `SetupTimer`. //! let output = machine.consume(&CircuitBreakerInput::Unsuccesful).unwrap(); //! // Check the output //! if output == Some(CircuitBreakerOutput::SetupTimer) { //! // Set up the timer... //! } //! // Check the state //! if machine.state() == &CircuitBreakerState::Open { //! // Do something... //! } //! ``` //! //! As you can see, the following entities are generated: //! //! * An empty structure `CircuitBreaker` that implements the `StateMachineImpl` //! trait. //! * Enums `CircuitBreakerState`, `CircuitBreakerInput` and //! `CircuitBreakerOutput` that represent the state, the input alphabet and //! the output alphabet respectively. //! //! Note that if there is no outputs in the specification, the output alphabet //! is set to `()`. The set of states and the input alphabet must be non-empty //! sets. //! //! ## Without DSL //! //! The `state_machine` macro has limited capabilities (for example, a state //! cannot carry any additional data), so in certain complex cases a user might //! want to write a more complex state machine by hand. //! //! All you need to do to build a state machine is to implement the //! `StateMachineImpl` trait and use it in conjuctions with some of the provided //! wrappers (for now there is only `StateMachine`). //! //! You can see an example of the Circuit Breaker state machine in the //! [project repository][repo]. //! //! [repo]: https://github.com/eugene-babichenko/rust-fsm/blob/master/tests/circuit_breaker.rs #![cfg_attr(not(feature = "std"), no_std)] use core::fmt; #[cfg(feature = "std")] use std::error::Error; #[cfg(feature = "dsl")] pub use rust_fsm_dsl::state_machine; /// This trait is designed to describe any possible deterministic finite state /// machine/transducer. This is just a formal definition that may be /// inconvenient to be used in practical programming, but it is used throughout /// this library for more practical things. pub trait StateMachineImpl { /// The input alphabet. type Input; /// The set of possible states. type State; /// The output alphabet. type Output; /// The initial state of the machine. // allow since there is usually no interior mutability because states are enums #[allow(clippy::declare_interior_mutable_const)] const INITIAL_STATE: Self::State; /// The transition fuction that outputs a new state based on the current /// state and the provided input. Outputs `None` when there is no transition /// for a given combination of the input and the state. fn transition(state: &Self::State, input: &Self::Input) -> Option<Self::State>; /// The output function that outputs some value from the output alphabet /// based on the current state and the given input. Outputs `None` when /// there is no output for a given combination of the input and the state. fn output(state: &Self::State, input: &Self::Input) -> Option<Self::Output>; } /// A convenience wrapper around the `StateMachine` trait that encapsulates the /// state and transition and output function calls. pub struct StateMachine<T: StateMachineImpl> { state: T::State, } #[derive(Debug, Clone)] /// An error type that represents that the state transition is impossible given /// the current combination of state and input. pub struct TransitionImpossibleError; impl<T> StateMachine<T> where T: StateMachineImpl, { /// Create a new instance of this wrapper which encapsulates the initial /// state. pub fn new() -> Self { Self::from_state(T::INITIAL_STATE) } /// Create a new instance of this wrapper which encapsulates the given /// state. pub fn from_state(state: T::State) -> Self { Self { state } } /// Consumes the provided input, gives an output and performs a state /// transition. If a state transition with the current state and the /// provided input is not allowed, returns an error. pub fn consume( &mut self, input: &T::Input, ) -> Result<Option<T::Output>, TransitionImpossibleError> { if let Some(state) = T::transition(&self.state, input) { let output = T::output(&self.state, input); self.state = state; Ok(output) } else { Err(TransitionImpossibleError) } } /// Returns the current state. pub fn state(&self) -> &T::State { &self.state } } impl<T> Default for StateMachine<T> where T: StateMachineImpl, { fn default() -> Self { Self::new() } } impl fmt::Display for TransitionImpossibleError { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!( f, "cannot perform a state transition from the current state with the provided input" ) } } #[cfg(feature = "std")] impl Error for TransitionImpossibleError { fn source(&self) -> Option<&(dyn Error + 'static)> { None } }