Finite state machines in rust; bendns fork to add types.
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 78 |
1 files changed, 38 insertions, 40 deletions
@@ -12,24 +12,24 @@ 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 +- 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. +- The initial state of the machine. -Note that on the implementation level such abstraction allows build any type -of state machines: +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 +- 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,9 +46,9 @@ of 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 -`rust-fsm = { version = "0.7", default-features = false, features = ["dsl"] }` +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 +58,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 @@ -86,17 +86,16 @@ state_machine! { This code sample: -* Defines a state machine called `circuit_breaker`; -* Derives the `Debug` trait for it. All attributes you use here (like +- Defines a state machine called `circuit_breaker`; +- 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`. +- 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: @@ -120,20 +119,19 @@ if let circuit_breaker::State::Open = machine.state() { The following entities are generated: -* An empty structure `circuit_breaker::Impl` that implements the +- An empty structure `circuit_breaker::Impl` that implements the `StateMachineImpl` trait. -* Enums `circuit_breaker::State`, `circuit_breaker::Input` and +- Enums `circuit_breaker::State`, `circuit_breaker::Input` and `circuit_breaker::Output` that represent the state, the input alphabet and the output alphabet respectively. -* Type alias `circuit_breaker::StateMachine` that expands to -`StateMachine<circuit_breaker::Impl>`. +- 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 attributes (e.g. `derive`, `repr`) are applied to it. -Within the `state_machine` macro you must define at least one state -transition. +Within the `state_machine` macro you must define at least one state transition. #### Visibility @@ -211,16 +209,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 |