Finite state machines in rust; bendns fork to add types.
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 100 |
1 files changed, 39 insertions, 61 deletions
@@ -1,36 +1,21 @@ -# A framework and a DSL for building finite state machines in Rust - [![Documentation][docs-badge]][docs-link] [![Latest Version][crate-badge]][crate-link] -[](https://www.buymeacoffee.com/ybabichenko) - 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 +The essential part of this crate is the [`StateMachine`] 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. +- 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 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. ## Feature flags @@ -46,8 +31,8 @@ state machines: ## 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 +This library has the feature named `std` which is enabled by default. You +may want to import this library as `rust-fsm = { version = "0.8", 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`). @@ -58,9 +43,9 @@ 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). +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 @@ -73,7 +58,7 @@ state_machine! { #[derive(Debug)] #[repr(C)] /// A Circuit Breaker state machine. - circuit_breaker(Closed) + CircuitBreaker => Result => Action Closed => Unsuccessful => Open [SetupTimer], Open => TimerTriggered => HalfOpen, @@ -86,46 +71,40 @@ state_machine! { This code sample: -- Defines a state machine called `circuit_breaker`; +- Defines a state machine called `CircuitBreaker`; - Derives the `Debug` trait for it. All attributes you use here (like - `#[repr(C)]`) will be applied to all types generated by this macro. If you - want to apply attributes or a docstring to the `mod` generated by this macro, - just put it before the macro invocation. -- 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`. + `#[repr(C)]`) will be applied to all types generated by this macro. +- 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 = circuit_breaker::StateMachine::new(); +let mut machine = CircuitBreaker::Closed; // Consume the `Successful` input. No state transition is performed. -let _ = machine.consume(circuit_breaker::Input::Successful); +let _ = machine.consume(Result::Successful); // Consume the `Unsuccesful` input. The machine is moved to the `Open` // state. The output is `SetupTimer`. -let output = machine.consume(circuit_breaker::Input::Unsuccessful).unwrap(); +let output = machine.consume(Result::Unsuccessful).unwrap(); // Check the output -if let Some(circuit_breaker::Output::SetupTimer) = output { +if let Some(Action::SetupTimer) = output { // Set up the timer... } // Check the state -if let circuit_breaker::State::Open = machine.state() { +if let CircuitBreaker::Open = machine { // Do something... } ``` The following entities are generated: -- An empty structure `circuit_breaker::Impl` that implements the - `StateMachineImpl` trait. -- Enums `circuit_breaker::State`, `circuit_breaker::Input` and - `circuit_breaker::Output` that represent the state, the input alphabet and the +- Enums `CircuitBreaker`, `Result` and + `Action` that represent the state, the input alphabet and the output alphabet respectively. -- Type alias `circuit_breaker::StateMachine` that expands to - `StateMachine<circuit_breaker::Impl>`. Note that if there is no outputs in the specification, the output alphabet is an empty enum and due to technical limitations of many Rust attributes, no @@ -141,13 +120,13 @@ You can specify visibility like this: use rust_fsm::*; state_machine! { - pub CircuitBreaker(Closed) + pub CircuitBreaker => Result => Action - Closed(Unsuccessful) => Open [SetupTimer], - Open(TimerTriggered) => HalfOpen, + Closed => Unsuccessful => Open [SetupTimer], + Open => TimerTriggered => HalfOpen, HalfOpen => { Successful => Closed, - Unsuccessful => Open [SetupTimer], + Unsuccessful => Open [SetupTimer] } } ``` @@ -180,11 +159,10 @@ pub enum Output { } state_machine! { - #[state_machine(input(crate::Input), state(crate::State), output(crate::Output))] - circuit_breaker(Closed) + crate::State => crate::Input => crate::Output - Closed(Unsuccessful) => Open [SetupTimer], - Open(TimerTriggered) => HalfOpen, + Closed => Unsuccessful => Open [SetupTimer], + Open => TimerTriggered => HalfOpen, HalfOpen => { Successful => Closed, Unsuccessful => Open [SetupTimer] @@ -209,16 +187,16 @@ cargo doc -p doc-example --open ### 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. +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]. +You can see an example of the Circuit Breaker state machine in the +[project repository][repo]. [repo]: https://github.com/eugene-babichenko/rust-fsm [docs-badge]: https://docs.rs/rust-fsm/badge.svg |