statig

用于设计事件驱动系统的分层状态机。

特性

• 分层状态机
• 状态本地存储
• 兼容#![no_std]，状态机定义在只读存储器中，不进行堆内存分配。
• (可选) 用于减少模板代码的宏。
• 支持泛型。
• 支持异步动作和处理程序（仅在std上）。

概览

• Statig在行动
• 概念
  • 状态
  • 超级状态
  • 动作
  • 共享存储
  • 状态本地存储
  • 上下文
  • 检查
  • 异步
• 实现
• 常见问题解答
• 致谢

Statig在行动

一个简单的闪烁状态机

┌─────────────────────────┐                   
│         Blinking        │◀─────────┐        
│    ┌───────────────┐    │          │        
│ ┌─▶│     LedOn     │──┐ │  ┌───────────────┐
│ │  └───────────────┘  │ │  │  NotBlinking  │
│ │  ┌───────────────┐  │ │  └───────────────┘
│ └──│     LedOff    │◀─┘ │          ▲        
│    └───────────────┘    │──────────┘        
└─────────────────────────┘                   

#[derive(Default)]
pub struct Blinky;

pub enum Event {
    TimerElapsed,
    ButtonPressed
}

#[state_machine(initial = "State::led_on()")]
impl Blinky {
    #[state(superstate = "blinking")]
    fn led_on(event: &Event) -> Response<State> {
        match event {
            Event::TimerElapsed => Transition(State::led_off()),
            _ => Super
        }
    }

    #[state(superstate = "blinking")]
    fn led_off(event: &Event) -> Response<State> {
        match event {
            Event::TimerElapsed => Transition(State::led_on()),
            _ => Super
        }
    }

    #[superstate]
    fn blinking(event: &Event) -> Response<State> {
        match event {
            Event::ButtonPressed => Transition(State::not_blinking()),
            _ => Super
        }
    }

    #[state]
    fn not_blinking(event: &Event) -> Response<State> {
        match event {
            Event::ButtonPressed => Transition(State::led_on()),
            _ => Super
        }
    }
}

fn main() {
    let mut state_machine = Blinky::default().state_machine();

    state_machine.handle(&Event::TimerElapsed);
    state_machine.handle(&Event::ButtonPressed);
}

(查看带有注释的完整代码的macro/blinky示例。或者查看no_macro/blinky以查看不使用宏的版本。

概念

状态

状态通过在impl块中编写方法，并添加#[state]属性到它们来定义。当将事件提交给状态机时，将调用与当前状态关联的方法来处理它。默认情况下，该事件映射到方法的event参数。

#[state]
fn led_on(event: &Event) -> Response<State> {
    Transition(State::led_off())
}

每个状态都必须返回一个Response。一个Response可以是以下三者之一

• Handled：已处理事件。
• Transition：转换到另一个状态。
• Super：将事件延迟到父超级状态。

超级状态

超级状态允许您创建状态层次结构。状态可以通过返回 Super 响应来将事件延迟到其超级状态。

#[state(superstate = "blinking")]
fn led_on(event: &Event) -> Response<State> {
    match event {
        Event::TimerElapsed => Transition(State::led_off()),
        Event::ButtonPressed => Super
    }
}

#[superstate]
fn blinking(event: &Event) -> Response<State> {
    match event {
        Event::ButtonPressed => Transition(State::not_blinking()),
        _ => Super
    }
}

超级状态本身也可以有超级状态。

动作

在转换过程中进入或离开状态时运行操作。

#[state(entry_action = "enter_led_on", exit_action = "exit_led_on")]
fn led_on(event: &Event) -> Response<State> {
    Transition(State::led_off())
}

#[action]
fn enter_led_on() {
    println!("Entered on");
}

#[action]
fn exit_led_on() {
    println!("Exited on");
}

共享存储

如果您的状态机实现的类型有任何字段，您可以在所有状态、超级状态或操作中访问它们。

#[state]
fn led_on(&mut self, event: &Event) -> Response<State> {
    match event {
        Event::TimerElapsed => {
            self.led = false;
            Transition(State::led_off())
        }
        _ => Super
    }
}

或者，您还可以在进入操作中设置 led。

#[action]
fn enter_led_off(&mut self) {
    self.led = false;
}

状态本地存储

有时您有仅在特定状态中存在的数据。您可以将此数据添加为状态处理器的输入，而不是将其添加到共享存储中，并可能需要解包 Option<T>。

#[state]
fn led_on(counter: &mut u32, event: &Event) -> Response<State> {
    match event {
        Event::TimerElapsed => {
            *counter -= 1;
            if *counter == 0 {
                Transition(State::led_off())
            } else {
                Handled
            }
        }
        Event::ButtonPressed => Transition(State::led_on(10))
    }
}

counter 仅在 led_on 状态中可用，但也可以在其超级状态和操作中访问。

上下文

当状态机在更大的系统中使用时，有时需要传递外部可变上下文。默认情况下，此上下文映射到方法的方法参数 context。

#[state]
fn led_on(context: &mut Context, event: &Event) -> Response<State> {
    match event {
        Event::TimerElapsed => {
            context.do_something();
            Handled
        }
        _ => Super
    }
}

然后您将需要使用 handle_with_context 方法向状态机提交事件。

state_machine.handle_with_context(&Event::TimerElapsed, &mut context);

检查

为了日志记录目的，您可以在状态机执行过程中特定点调用两个回调。

• on_dispatch 在将事件分发到特定状态或超级状态之前调用。
• on_transition 在转换发生后调用。

#[state_machine(
    initial = "State::on()",
    on_dispatch = "Self::on_dispatch",
    on_transition = "Self::on_transition",
    state(derive(Debug)),
    superstate(derive(Debug))
)]
impl Blinky {
    ...
}

impl Blinky {
    fn on_transition(&mut self, source: &State, target: &State) {
        println!("transitioned from `{:?}` to `{:?}`", source, target);
    }

    fn on_dispatch(&mut self, state: StateOrSuperstate<Blinky>, event: &Event) {
        println!("dispatched `{:?}` to `{:?}`", event, state);
    }
}

异步

所有处理程序和操作都可以是异步的。（目前仅在 std 上可用，并需要启用 async 功能）。

#[state_machine(initial = "State::led_on()")]
impl Blinky {
    #[state]
    async fn led_on(event: &Event) -> Response<State> {
        match event {
            Event::TimerElapsed => Transition(State::led_off()),
            _ => Super
        }
    }
}

然后，#[state_machine] 宏将自动检测正在使用异步函数，并生成异步状态机。

async fn main() {
    let mut state_machine = Blinky::default().state_machine();

    state_machine.handle(&Event::TimerElapsed).await;
    state_machine.handle(&Event::ButtonPressed).await;
}

实现

大多数实现细节都由 #[state_machine] 宏处理，但了解幕后发生的事情总是很有价值。此外，您会发现生成的代码实际上非常简单，可以很容易地手动编写，所以如果您更喜欢避免使用宏，这是完全可以实现的。

statig 的目标是表示层次状态机。概念上，层次状态机可以被视为树。

                          ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐             
                                    Top                       
                          └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘             
                                     │                        
                        ┌────────────┴────────────┐           
                        │                         │           
             ┌─────────────────────┐   ╔═════════════════════╗
             │      Blinking       │   ║     NotBlinking     ║
             │─────────────────────│   ╚═════════════════════╝
             │ counter: &'a usize  │                          
             └─────────────────────┘                          
                        │                                     
           ┌────────────┴────────────┐                        
           │                         │                        
╔═════════════════════╗   ╔═════════════════════╗             
║        LedOn        ║   ║        LedOff       ║             
║─────────────────────║   ║─────────────────────║             
║ counter: usize      ║   ║ counter: usize      ║             
╚═════════════════════╝   ╚═════════════════════╝

树边缘的节点称为叶子状态，在 statig 中由枚举表示。如果数据仅在特定状态中存在，我们可以赋予该状态对数据的所有权。这被称为“状态本地存储”。例如，counter 仅存在于 LedOn 和 LedOff 状态中。

enum State {
    LedOn { counter: usize },
    LedOff { counter: usize },
    NotBlinking
}

如 Blinking 之类的状态称为超级状态。它们定义了子状态的共享行为。超级状态也由枚举表示，但它们不拥有自己的数据，而是从底层状态借用。

enum Superstate<'sub> {
    Blinking { counter: &'sub usize }
}

状态与其处理程序之间的关联通过 State 和 Superstate 特性中的 call_handler() 方法表达。

impl statig::State<Blinky> for State {
    fn call_handler(&mut self, blinky: &mut Blinky, event: &Event) -> Response<Self> {
        match self {
            State::LedOn { counter } => blinky.led_on(counter, event),
            State::LedOff { counter } => blinky.led_off(counter, event),
            State::NotBlinking => blinky.not_blinking(event)
        }
    }
}

impl statig::Superstate<Blinky> for Superstate {
    fn call_handler(&mut self, blinky: &mut Blinky, event: &Event) -> Response<Self> {
        match self {
            Superstate::Blinking { counter } => blinky.blinking(counter, event),
        }
    }
}

impl statig::State<Blinky> for State {
    
    ...

    fn call_entry_action(&mut self, blinky: &mut Blinky) {
        match self {
            State::LedOn { counter } => blinky.enter_led_on(counter),
            State::LedOff { counter } => blinky.enter_led_off(counter),
            State::NotBlinking => blinky.enter_not_blinking()
        }
    }

    fn call_exit_action(&mut self, blinky: &mut Blinky) {
        match self {
            State::LedOn { counter } => blinky.exit_led_on(counter),
            State::LedOff { counter } => blinky.exit_led_off(counter),
            State::NotBlinking => blinky.exit_not_blinking()
        }
    }
}

impl statig::Superstate<Blinky> for Superstate {

    ...

    fn call_entry_action(&mut self, blinky: &mut Blinky) {
        match self {
            Superstate::Blinking { counter } => blinky.enter_blinking(counter),
        }
    }

    fn call_exit_action(&mut self, blinky: &mut Blinky) {
        match self {
            Superstate::Blinking { counter } => blinky.exit_blinking(counter),
        }
    }
}

impl statig::State<Blinky> for State {

    ...

    fn superstate(&mut self) -> Option<Superstate<'_>> {
        match self {
            State::LedOn { counter } => Some(Superstate::Blinking { counter }),
            State::LedOff { counter } => Some(Superstate::Blinking { counter }),
            State::NotBlinking => None
        }
    }
}

impl<'sub> statig::Superstate<Blinky> for Superstate<'sub> {

    ...

    fn superstate(&mut self) -> Option<Superstate<'_>> {
        match self {
            Superstate::Blinking { .. } => None
        }
    }
}

impl IntoStateMachine for Blinky {
    type State = State;

    type Superstate<'sub> = Superstate<'sub>;

    type Event<'evt> = Event;

    type Context<'ctx> = Context;

    const INITIAL: State = State::off(10);
}