Need help with sm?
Click the โ€œchatโ€ button below for chat support from the developer who created it, or find similar developers for support.

About the developer

164 Stars 8 Forks Other 157 Commits 5 Opened issues


๐Ÿš€ SM โ€“ a static State Machine library

Services available


Need anything else?

Contributors list

SM serves as one of the building blocks for an open-source game about space engineering and exploration. This library is in active use and development.

SM aims to be a safe, fast and simple state machine library.

  • safe โ€” Rust's type system, ownership model and exhaustive pattern matching prevent you from mis-using your state machines

  • fast โ€” zero runtime overhead, the machine is 100% static, all validation happens at compile-time

  • simple โ€” five traits, and one optional declarative macro, control-flow only, no business logic attached

Latest Crate Version Discord Chat Build Status Test Coverage Status

Using this library, you declaratively define your state machines as as set of states, connected via transitions, triggered by events. You can query the current state of the machine, or pattern match against all possible machine variants.

The implementation ensures a zero-sized abstraction that uses Rust's type-system and ownership model to guarantee valid transitions between states using events, and makes sure previous states are no longer accessible after transitioning away to another state. Rust validates correct usage of the state machine at compile-time, no runtime checking occurs when using the library.

The library exposes the

macro, which allows you to declaratively build the state machine.


Quick Example

extern crate sm;
use sm::sm;

sm! { Lock { InitialStates { Locked, Unlocked }

    TurnKey {
        Locked => Unlocked
        Unlocked => Locked

    Break {
        Locked, Unlocked => Broken


fn main() { use Lock::*; let lock = Machine::new(Locked); let lock = lock.transition(TurnKey);

assert_eq!(lock.state(), Unlocked);
assert_eq!(lock.trigger().unwrap(), TurnKey);


Descriptive Example

The below example explains step-by-step how to create a new state machine using the provided macro, and then how to use the created machine in your code by querying states, and transitioning between states by triggering events.

Declaring a new State Machine

First, we import the macro from the crate:

extern crate sm;
use sm::sm;

Next, we initiate the macro declaration:

sm! {

Then, provide a name for the machine, and declare a list of allowed initial states:

    Lock {
        InitialStates { Locked, Unlocked }

Finally, we declare one or more events and the associated transitions:

        TurnKey {
            Locked => Unlocked
            Unlocked => Locked

    Break {
        Locked, Unlocked => Broken


And we're done. We've defined our state machine structure, and the valid transitions, and can now use this state machine in our code.

Using your State Machine

You can initialise the machine as follows:

let sm = Lock::Machine::new(Lock::Locked);

We can make this a bit less verbose by bringing our machine into scope:

use Lock::*;
let sm = Machine::new(Locked);

We've initialised our machine in the

state. You can get the current state of the machine by sending the
method to the machine:
let state = sm.state();
assert_eq!(state, Locked);

While you can use

with conditional branching to execute your code based on the current state, this can be a bit tedious, it's less idiomatic, and it prevents you from using one extra compile-time validation tool in our toolbox: using Rust's exhaustive pattern matching requirement to ensure you've covered all possible state variants in your business logic.


returns the state as a unit-like struct (which itself is a ZST, or Zero Sized Type), you can use the
method to get the state machine back as an enum variant.

Using the enum variant and pattern matching, you are able to do the following:

use Lock::Variant::*;

match sm.as_enum() { InitialLocked(m) => { assert_eq!(m.state(), Locked); assert!(m.trigger().is_none()); } InitialUnlocked(m) => { assert_eq!(m.state(), Unlocked); assert!(m.trigger().is_none()); } LockedByTurnKey(m) => { assert_eq!(m.state(), Locked); assert_eq!(m.trigger().unwrap(), TurnKey); } UnlockedByTurnKey(m) => { assert_eq!(m.state(), Unlocked); assert_eq!(m.trigger().unwrap(), TurnKey); } BrokenByBreak(m) => { assert_eq!(m.state(), Broken); assert_eq!(m.trigger().unwrap(), Break); } }

Each state configured with

has its own variant named
. Next to those, each valid state + event combination also has its own variant, named

The compiler won't be satisfied until you've either exhausted all possible enum variants, or you explicitly opt-out of matching all variants, either way, you can be much more confident that your code won't break if you add a new state down the road, but forget to add it to a pattern match somewhere deep inside your code-base.

To transition this machine to the

state, we send the
method, using the
let sm = sm.transition(TurnKey);
assert_eq!(sm.state(), Unlocked);

Because multiple events can lead to a single state, it's also important to be able to determine what event caused the machine to transition to the current state. We can ask this information using the

assert_eq!(sm.trigger().unwrap(), TurnKey);


method returns
if no state transition has taken place yet (ie. the machine is still in its initial state), and
if one or more transitions have taken place.

A word about Type-Safety and Ownership

It's important to realise that we've consumed the original machine in the above example when we transitioned the machine to a different state, and got a newly initialised machine back in the


This allows us to safely use the machine without having to worry about multiple readers using the machine in different states.

All these checks are applied on compile-time, so the following example would fail to compile:

let sm2 = sm.transition(TurnKey);
assert_eq!(sm.state(), Locked);

This fails with the following compilation error:

error[E0382]: use of moved value: `sm`
  --> src/
22 | let sm2 = sm.transition(TurnKey);
   |           -- value moved here
23 | assert_eq!(sm.state(), Locked);
   |            ^^ value used here after move
   = note: move occurs because `sm` has type `Lock::Machine<:locked>`, which does not implement the `Copy` trait

Similarly, we cannot execute undefined transitions, these are also caught by the compiler:

assert_eq!(sm.state(), Broken);

let sm = sm.transition(TurnKey);

This fails with the following compilation error:

error[E0599]: no method named `transition` found for type `Lock::Machine<:broken>` in the current scope
  --> src/
4  | sm! {
   | --- method `transition` not found for this
25 | let sm = sm.transition(TurnKey);
   |             ^^^^^^^^^^
   = help: items from traits can only be used if the trait is implemented and in scope
   = note: the following trait defines an item `transition`, perhaps you need to implement it:
           candidate #1: `sm::Transition`

The error message is not great (and can potentially be improved in the future), but any error telling you

is not implemented, or the passed in event type is invalid is an indication that you are trying to execute an illegal state transition.

Finally, we are confined to initialising a new machine in only the states that we defined in

let sm = Machine::new(Broken);

This results in the following error:

error[E0277]: the trait bound `Lock::Broken: sm::InitialState` is not satisfied
  --> src/
21 | let sm = Machine::new(Broken);
   |          ^^^^^^^^^^^^ the trait `sm::InitialState` is not implemented for `Lock::Broken`
   = note: required because of the requirements on the impl of `sm::NewMachine<:broken>` for `Lock::Machine<:broken>`

The End ๐Ÿ‘‹

And that's it! There's nothing else to it, except a declarative โ€“ and easy to read โ€“ state machine construction macro, and a type-safe and ownership-focused way of dealing with states and transitions, without any runtime overhead.

Go forth and transition!


Licensed under either of

  • Apache License, Version 2.0, (LICENSE-APACHE or
  • MIT license (LICENSE-MIT or


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.