20 releases
0.8.0 | Aug 9, 2024 |
---|---|
0.7.0 | Jul 3, 2024 |
0.6.0 | Nov 2, 2022 |
0.5.1 | Feb 5, 2022 |
0.1.2 | May 6, 2019 |
#31 in Embedded development
10,802 downloads per month
Used in 8 crates
(7 directly)
59KB
200 lines
smlang: A no_std
State Machine Language DSL in Rust
A state machine language DSL based on the syntax of Boost-SML.
smlang
is a procedural macro library creating a state machine language DSL, whose aim to facilitate the
use of state machines, as they quite fast can become overly complicated to write and get an
overview of.
The library supports both async
and non-async
code.
Transition DSL
Below is a sample of the DSL. For a full description of the statemachine
macro, please reference
the DSL document.
statemachine!{
transitions: {
*SrcState1 + Event1 [ guard1 ] / action1 = DstState2, // * denotes starting state
SrcState2 + Event2 [ guard2 ] / action2 = DstState1,
}
// ...
}
Where guard
and action
are optional and can be left out. A guard
is a function which returns
Ok(true)
if the state transition should happen - otherwise, the transition should not happen.
The action
functions are run during the state machine transition.
This implies that any state machine must be written as a list of transitions.
The DSL supports wildcards and pattern matching for input states similar to rust pattern matching:
statemachine!{
transitions: {
*State1 | State3 + ToState2 = State2,
State1 | State2 + ToState3 = State3,
_ + ToState4 = State4,
State4 + ToState1 = State1,
}
// ...
}
Which is equivalent to:
statemachine!{
transitions: {
*State1 + ToState2 = State2,
State3 + ToState2 = State2,
State1 + ToState3 = State3,
State2 + ToState3 = State3,
State1 + ToState4 = State4,
State2 + ToState4 = State4,
State3 + ToState4 = State4,
State4 + ToState4 = State4,
State4 + ToState1 = State1,
}
// ...
}
See example examples/input_state_pattern_match.rs
for a usage example.
Internal transitions
The DSL supports internal transitions. Internal transition allow to accept an event and process an action, and then stay in the current state. Internal transitions can be specified explicitly, e.g.
State2 + Event2 / event2_action = State2,
or
State2 + Event2 / event2_action = _,
or implicitly, by omitting the target state including '='.
State2 + Event2 / event2_action,
It is also possible to define wildcard implicit (or explicit using '_') internal transitions.
statemachine! {
transitions: {
*State1 + Event2 = State2,
State1 + Event3 = State3,
State1 + Event4 = State4,
_ + Event2 / event2_action,
},
}
The example above demonstrates how you could make Event2 acceptable for any state, not covered by any of the previous transitions, and to do an action to process it.
It is equivalent to:
statemachine! {
transitions: {
*State1 + Event2 = State2,
State1 + Event3 = State3,
State1 + Event4 = State4,
State2 + Event2 / event2_action = State2,
State3 + Event2 / event2_action = State3,
State4 + Event2 / event2_action = State4,
},
}
See also tests: test_internal_transition_with_data()
or test_wildcard_states_and_internal_transitions()
for a usage example.
Guard expressions
Guard expression in square brackets [] allows to define a boolean expressions of multiple guard functions. For example:
statemachine! {
transitions: {
*Init + Login(Entry) [valid_entry] / attempt = LoggedIn,
Init + Login(Entry) [!valid_entry && !too_many_attempts] / attempt = Init,
Init + Login(Entry) [!valid_entry && too_many_attempts] / attempt = LoginDenied,
LoggedIn + Logout / reset = Init,
}
}
Guard expressions may consist of guard function names, and their combinations with &&, || and ! operations.
Multiple guarded transitions for the same state and triggering event
Multiple guarded transitions for the same state and triggering event are supported (see the example above). It is assumed that only one guard is enabled in such a case to avoid a conflict over which transition should be selected. However, if there is a conflict and more than one guard is enabled, the first enabled transition, in the order they appear in the state machine definition, will be selected.
State machine context
The state machine needs a context to be defined.
The StateMachineContext
is generated from the statemachine!
proc-macro and is what implements
guards and actions, and data that is available in all states within the state machine and persists
between state transitions:
statemachine!{
transitions: {
State1 + Event1 = State2,
}
// ...
}
pub struct Context;
impl StateMachineContext for Context {}
fn main() {
let mut sm = StateMachine::new(Context);
// ...
}
See example examples/context.rs
for a usage example.
State data
Any state may have some data associated with it:
pub struct MyStateData(pub u32);
statemachine!{
transitions: {
State1(MyStateData) + Event1 = State2,
}
// ...
}
See example examples/state_with_data.rs
for a usage example.
If the starting state contains data, this data must be provided after the context when creating a new machine.
pub struct MyStateData(pub u32);
statemachine!{
transitions: {
State2 + Event2 / action = State1(MyStateData),
*State1(MyStateData) + Event1 = State2,
// ...
}
// ...
}
// ...
let mut sm = StateMachine::new(Context, MyStateData(42));
State data may also have associated lifetimes which the statemachine!
macro will pick up and add the States
enum and StateMachine
structure. This means the following will also work:
pub struct MyStateData<'a>(&'a u32);
statemachine! {
transitions: {
*State1 + Event1 / action = State2,
State2(MyStateData<'a>) + Event2 = State1,
// ...
}
// ...
}
See example examples/state_with_reference_data.rs
for a usage example.
Event data
Data may be passed along with an event into the guard
and action
:
pub struct MyEventData(pub u32);
statemachine!{
transitions: {
State1 + Event1(MyEventData) [guard] = State2,
}
// ...
}
Event data may also have associated lifetimes which the statemachine!
macro will pick up and add the Events
enum. This means the following will also work:
pub struct MyEventData<'a>(pub &'a u32);
statemachine!{
transitions: {
State1 + Event1(MyEventData<'a>) [guard1] = State2,
State1 + Event2(&'a [u8]) [guard2] = State3,
}
// ...
}
See example examples/event_with_data.rs
for a usage example.
Guard and Action syntax
See example examples/guard_action_syntax.rs
for a usage-example.
Async Guard and Action
Guards and actions may both be optionally async
:
use smlang::{async_trait, statemachine};
statemachine! {
transitions: {
*State1 + Event1 [guard1] / async action1 = State2,
State2 + Event2 [async guard2] / action2 = State3,
}
}
pub struct Context {
// ...
}
impl StateMachineContext for Context {
async fn action1(&mut self) -> () {
// ...
}
async fn guard2(&mut self) -> Result<(), ()> {
// ...
}
fn guard1(&mut self) -> Result<(), ()> {
// ...
}
fn action2(&mut self) -> () {
// ...
}
}
See example examples/async.rs
for a usage-example.
State Machine Examples
Here are some examples of state machines converted from UML to the State Machine Language DSL.
Runnable versions of each example is available in the examples
folder. The .png
s are generated
with the graphviz
feature.
Linear state machine
DSL implementation:
statemachine!{
transitions: {
*State1 + Event1 = State2,
State2 + Event2 = State3,
}
}
This example is available in ex1.rs
.
Looping state machine
DSL implementation:
statemachine!{
transitions: {
*State1 + Event1 = State2,
State2 + Event2 = State3,
State3 + Event3 = State2,
}
}
This example is available in ex2.rs
.
Using guards and actions
DSL implementation:
statemachine!{
transitions: {
*State1 + Event1 [guard] / action = State2,
}
}
This example is available in ex3.rs
.
Using entry and exit functions in transitions
The statemachine will create for all states an on_entry_
and on_exit_
function.
If the are not used, they will be optimized away by the compiler. An example be
found in on_entry_on_exit_generic
.
Transition callback
The statemachine will call for every transition a transition callback. This function
is called with both the old state and new state as arguments. An example can be found
in dominos
.
Helpers
Auto-derive certain traits for states and events
Setting derive_events
and derive_states
fields to an array of traits adds a derive expression to Events
and States
enums respectively. To derive Display, use derive_more::Display
.
use core::Debug;
use derive_more::Display;
// ...
statemachine!{
derive_states: [Debug, Display],
derive_events: [Debug, Display],
transitions: {
*State1 + Event1 = State2,
}
}
// ...
println!("Current state: {}", sm.state().unwrap());
println!("Expected state: {}", States::State1);
println!("Sending event: {}", Events::Event1);
// ...
Hooks for logging events, guards, actions, and state transitions
The StateMachineContext
trait defines (and provides default, no-op implementations for) functions that are called for each event, guard, action, and state transition. You can provide your
own implementations which plug into your preferred logging mechanism.
fn log_process_event(&self, current_state: &States, event: &Events) {}
fn log_guard(&self, guard: &'static str, result: &Result<(), ()>) {}
fn log_action(&self, action: &'static str) {}
fn log_state_change(&self, new_state: &States) {}
See examples/state_machine_logger.rs
for an example which uses derive_states
and derive_events
to derive Debug
implementations for easy logging.
Contributors
List of contributors in alphabetical order:
- Emil Fresk (@korken89)
- Mathias Koch (@MathiasKoch)
- Ryan Summers (@ryan-summers)
- Donny Zimmanck (@dzimmanck)
License
Licensed under either of
- Apache License, Version 2.0 LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0
- MIT license LICENSE-MIT or http://opensource.org/licenses/MIT
at your option.
Dependencies
~1.5MB
~37K SLoC