smarm-agent
531571bfa5
A `=> postpone` row (cast/call/info) defers the current event untouched, to be replayed after the next real transition. `handle` is now two-phase: a borrow-only postpone pre-pass that hands the event back as `Step::Postponed(ev)`, then the existing consuming `match (state, event)`. The loop owns a FIFO queue, drained in the new state ahead of further intake; a replayed event may postpone again. A postponed `call` keeps its Reply, so a later state answers it. `handle` returns `Step` (Postponed / Transitioned / Stayed) so the loop can see both deferral and transition without reading the state cell. `Resolution::Postpone` is removed: postpone is a pre-dispatch routing decision, not a consuming-dispatch outcome.
309 lines
12 KiB
Rust
309 lines
12 KiB
Rust
//! The hand-written **expansion target** of the `gen_statem!` macro: the same
|
|
//! machine as `examples/gen_statem_macro.rs`, written out in full so the
|
|
//! primitives can be judged standing on their own. The macro generates exactly
|
|
//! this shape; nothing here needs the macro to be correct or safe.
|
|
//!
|
|
//! The design:
|
|
//!
|
|
//! * States and events are real enums. An invalid state is unrepresentable;
|
|
//! there are no bitflags, no `u32` superpositions, no unsafe unions.
|
|
//!
|
|
//! * The dispatch `match (state, event)` IS the transition table. It is
|
|
//! *total* — no catch-all `_` arm — so:
|
|
//! - a forgotten (state, event) pair is a non-exhaustive `match` (E0004),
|
|
//! - a duplicated/conflicting row is `unreachable_patterns` (denied below).
|
|
//!
|
|
//! * Single-target rows name their target in the table; the handler (if any)
|
|
//! is side-effect-only. The table owns the target, so it cannot be wrong.
|
|
//!
|
|
//! * Branching rows have the handler return a per-row *successor enum*. A
|
|
//! target outside that enum is E0599; a missing one is E0004. (See
|
|
//! `UnlockOutcome` and `on_unlock`.)
|
|
//!
|
|
//! * Handlers are module-private. The only way to reach one is through the
|
|
//! actor's message interface via this table, so a handler that is never
|
|
//! wired in is dead code — and dead_code is denied below, making an orphan
|
|
//! handler a compile error.
|
|
//!
|
|
//! * Drops onto the `Machine` / `Resolution` / `Cx` primitives with no change
|
|
//! to `src/gen_statem.rs`.
|
|
//!
|
|
//! Default build is clean and runs. A BREAK-CASE MENU at the bottom documents
|
|
//! how to make each of the four guarantees fire.
|
|
//!
|
|
//! Run: `cargo run --example gen_statem_expanded`
|
|
|
|
#![deny(dead_code, unreachable_patterns)]
|
|
|
|
use smarm::run;
|
|
use smarm::gen_statem::{spawn, Cx, Machine, Reply, Resolution, Step, GenStatemRef};
|
|
|
|
// === user types ============================================================
|
|
|
|
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
|
|
enum Door {
|
|
Open,
|
|
Closed,
|
|
Locked,
|
|
}
|
|
|
|
struct Data {
|
|
enters: u32, // total state entries (incl. initial)
|
|
pushes: u32, // times a push closed the door
|
|
knocks: u32, // knocks answered (a Locked knock is postponed, then counted)
|
|
}
|
|
|
|
enum Cast {
|
|
Push,
|
|
Pull,
|
|
Lock,
|
|
Unlock(u32), // carries a key
|
|
Knock, // counted when the door is reachable; postponed while Locked
|
|
}
|
|
|
|
enum Call {
|
|
GetState(Reply<Door>),
|
|
GetEnters(Reply<u32>),
|
|
GetPushes(Reply<u32>),
|
|
GetKnocks(Reply<u32>),
|
|
}
|
|
|
|
enum Ev {
|
|
Cast(Cast),
|
|
Call(Call),
|
|
// The runtime's internal events. `Info` is out-of-band (here unused, so
|
|
// `()`); `StateTimeout` / `Timeout` are timer fires the loop feeds back in.
|
|
Info(()),
|
|
StateTimeout,
|
|
Timeout(&'static str),
|
|
}
|
|
|
|
const CODE: u32 = 1234;
|
|
|
|
// === per-row successor enum for the one branching row ======================
|
|
// `Locked + Unlock` may end in Closed (right key) or Locked (wrong key) — and
|
|
// nothing else. This type IS that declared set; `on_unlock` cannot name Open.
|
|
enum UnlockOutcome {
|
|
Closed,
|
|
Locked,
|
|
}
|
|
|
|
impl From<UnlockOutcome> for Door {
|
|
fn from(o: UnlockOutcome) -> Door {
|
|
match o {
|
|
UnlockOutcome::Closed => Door::Closed,
|
|
UnlockOutcome::Locked => Door::Locked,
|
|
}
|
|
}
|
|
}
|
|
|
|
// === module-private handlers (side effects / branch choice only) ===========
|
|
// Reachable solely through the table below. Orphan one and it is dead_code.
|
|
|
|
fn on_push(data: &mut Data) {
|
|
data.pushes += 1;
|
|
}
|
|
|
|
fn on_unlock(key: u32) -> UnlockOutcome {
|
|
if key == CODE {
|
|
UnlockOutcome::Closed
|
|
} else {
|
|
UnlockOutcome::Locked // wrong key: caller will see this == current -> stay
|
|
}
|
|
}
|
|
|
|
// === the machine ===========================================================
|
|
|
|
struct DoorSm {
|
|
state: Door,
|
|
data: Data,
|
|
}
|
|
|
|
impl DoorSm {
|
|
fn start(init: Door) -> GenStatemRef<DoorSm> {
|
|
spawn(DoorSm {
|
|
state: init,
|
|
data: Data { enters: 0, pushes: 0, knocks: 0 },
|
|
})
|
|
}
|
|
|
|
fn enter(&mut self, cx: &mut Cx<Ev>) {
|
|
self.data.enters += 1;
|
|
// A state-timeout: an Open door auto-closes after a quiet window. The
|
|
// loop auto-resets it on any transition, so it fires only if the door is
|
|
// still Open when it elapses.
|
|
if self.state == Door::Open {
|
|
cx.state_timeout(std::time::Duration::from_millis(5));
|
|
}
|
|
}
|
|
}
|
|
|
|
impl Machine for DoorSm {
|
|
type Ev = Ev;
|
|
|
|
fn state_timeout_ev() -> Ev {
|
|
Ev::StateTimeout
|
|
}
|
|
|
|
fn timeout_ev(name: &'static str) -> Ev {
|
|
Ev::Timeout(name)
|
|
}
|
|
|
|
fn on_start(&mut self, cx: &mut Cx<Ev>) {
|
|
self.enter(cx);
|
|
}
|
|
|
|
fn handle(&mut self, ev: Ev, cx: &mut Cx<Ev>) -> Step<Ev> {
|
|
let prev = self.state;
|
|
|
|
// ---- phase 1: postpone routing (borrow-only) ----------------------
|
|
// A deferred event is handed back untouched for the loop's postpone
|
|
// queue; no handler code runs on it. Here: a knock at a locked door.
|
|
// (The macro emits this as a `match (state, &ev)` yielding a bool; the
|
|
// hand-written form can just test directly.)
|
|
if let (Door::Locked, Ev::Cast(Cast::Knock)) = (prev, &ev) {
|
|
return Step::Postponed(ev);
|
|
}
|
|
|
|
// ---- phase 2: the consuming transition table ----------------------
|
|
// Total over (Door, Ev). Read it as the declared graph: each `=> To(x)`
|
|
// is an edge, each `=> Unhandled` an explicit refusal. The postponed
|
|
// pair above reappears as `unreachable!` so the match stays total.
|
|
let res: Resolution<Door> = match (self.state, ev) {
|
|
// --- Open -------------------------------------------------------
|
|
(Door::Open, Ev::Cast(Cast::Push)) => {
|
|
on_push(&mut self.data);
|
|
Resolution::To(Door::Closed)
|
|
}
|
|
(Door::Open, Ev::Cast(Cast::Knock)) => {
|
|
self.data.knocks += 1;
|
|
Resolution::To(prev)
|
|
}
|
|
(Door::Open, Ev::Cast(Cast::Pull | Cast::Lock | Cast::Unlock(_))) => {
|
|
Resolution::Unhandled
|
|
}
|
|
|
|
// --- Closed -----------------------------------------------------
|
|
(Door::Closed, Ev::Cast(Cast::Pull)) => Resolution::To(Door::Open),
|
|
(Door::Closed, Ev::Cast(Cast::Lock)) => Resolution::To(Door::Locked),
|
|
(Door::Closed, Ev::Cast(Cast::Knock)) => {
|
|
self.data.knocks += 1;
|
|
Resolution::To(prev)
|
|
}
|
|
(Door::Closed, Ev::Cast(Cast::Push | Cast::Unlock(_))) => Resolution::Unhandled,
|
|
|
|
// --- Locked (branching row: handler picks within UnlockOutcome) -
|
|
(Door::Locked, Ev::Cast(Cast::Unlock(key))) => {
|
|
Resolution::To(on_unlock(key).into())
|
|
}
|
|
// Routed out in phase 1; listed only to keep this match total.
|
|
(Door::Locked, Ev::Cast(Cast::Knock)) => {
|
|
unreachable!("postponed event is replayed, not dispatched here")
|
|
}
|
|
(Door::Locked, Ev::Cast(Cast::Push | Cast::Pull | Cast::Lock)) => {
|
|
Resolution::Unhandled
|
|
}
|
|
|
|
// --- state-independent queries (reply, then stay) ---------------
|
|
(_, Ev::Call(Call::GetState(r))) => {
|
|
r.reply(prev);
|
|
Resolution::To(prev)
|
|
}
|
|
(_, Ev::Call(Call::GetEnters(r))) => {
|
|
r.reply(self.data.enters);
|
|
Resolution::To(prev)
|
|
}
|
|
(_, Ev::Call(Call::GetPushes(r))) => {
|
|
r.reply(self.data.pushes);
|
|
Resolution::To(prev)
|
|
}
|
|
(_, Ev::Call(Call::GetKnocks(r))) => {
|
|
r.reply(self.data.knocks);
|
|
Resolution::To(prev)
|
|
}
|
|
|
|
// --- timeouts: an Open door auto-closes; others have none armed --
|
|
(Door::Open, Ev::StateTimeout) => Resolution::To(Door::Closed),
|
|
(_, Ev::StateTimeout) => Resolution::Unhandled,
|
|
(_, Ev::Timeout(name)) => {
|
|
// No named timeout is armed in this run; a real handler would
|
|
// dispatch on `name`. Acknowledge it to exercise the field.
|
|
let _ = name;
|
|
Resolution::Unhandled
|
|
}
|
|
|
|
// --- out-of-band info: silent drop (the gen_server default) ------
|
|
(_, Ev::Info(_)) => Resolution::Unhandled,
|
|
};
|
|
|
|
// ---- apply the resolution -----------------------------------------
|
|
match res {
|
|
Resolution::To(s) if s == prev => Step::Stayed, // stay: no enter
|
|
Resolution::To(s) => {
|
|
self.state = s; // sole writer of the state cell
|
|
cx.__reset_state_timeout(); // auto-reset across transitions
|
|
self.enter(cx);
|
|
Step::Transitioned
|
|
}
|
|
Resolution::Unhandled => {
|
|
cx.on_unhandled();
|
|
Step::Stayed
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
fn main() {
|
|
run(|| {
|
|
let door = DoorSm::start(Door::Closed);
|
|
|
|
door.send(Ev::Cast(Cast::Lock)).unwrap(); // Closed -> Locked
|
|
door.send(Ev::Cast(Cast::Knock)).unwrap(); // Locked: postponed (not yet counted)
|
|
door.send(Ev::Cast(Cast::Push)).unwrap(); // Locked: Push invalid -> Unhandled
|
|
door.send(Ev::Cast(Cast::Unlock(0))).unwrap(); // Locked: wrong key -> stay (knock still deferred)
|
|
door.send(Ev::Cast(Cast::Unlock(CODE))).unwrap(); // Locked -> Closed; deferred Knock replays here
|
|
door.send(Ev::Cast(Cast::Push)).unwrap(); // Closed: Push invalid -> Unhandled
|
|
door.send(Ev::Cast(Cast::Pull)).unwrap(); // Closed -> Open (arms 5ms auto-close)
|
|
door.send(Ev::Info(())).unwrap(); // out-of-band: silently dropped
|
|
|
|
// Wait past the auto-close window: the state-timeout fires and the door
|
|
// closes itself, with no further input. (`smarm::sleep` parks the actor
|
|
// without blocking a worker thread, so the timer wheel keeps turning.)
|
|
smarm::sleep(std::time::Duration::from_millis(40));
|
|
|
|
let st = door.call(|r| Ev::Call(Call::GetState(r))).unwrap();
|
|
let enters = door.call(|r| Ev::Call(Call::GetEnters(r))).unwrap();
|
|
let pushes = door.call(|r| Ev::Call(Call::GetPushes(r))).unwrap();
|
|
let knocks = door.call(|r| Ev::Call(Call::GetKnocks(r))).unwrap();
|
|
|
|
println!("state={st:?} enters={enters} pushes={pushes} knocks={knocks}");
|
|
assert_eq!(st, Door::Closed); // auto-closed by the state-timeout
|
|
assert_eq!(enters, 5); // Closed(start) + Locked + Closed + Open + Closed
|
|
assert_eq!(pushes, 0); // no push ever closed it this run
|
|
assert_eq!(knocks, 1); // the locked-door knock, replayed once unlocked
|
|
println!("ok");
|
|
});
|
|
}
|
|
|
|
// ===========================================================================
|
|
// BREAK-CASE MENU — each makes one compile-time guarantee fire.
|
|
//
|
|
// 1. ORPHAN HANDLER (dead_code -> error):
|
|
// add `fn on_slam(_d: &mut Data) {}` and don't reference it.
|
|
// => error: function `on_slam` is never used
|
|
//
|
|
// 2. CONFLICTING ROW (unreachable_patterns -> error):
|
|
// duplicate an arm, e.g. add a second
|
|
// `(Door::Open, Ev::Cast(Cast::Push)) => Resolution::Unhandled,`
|
|
// => error: unreachable pattern
|
|
//
|
|
// 3. MISSING PAIR (non-exhaustive match, E0004):
|
|
// delete the `(Door::Locked, Ev::Cast(Cast::Push | Cast::Pull | Cast::Lock))`
|
|
// arm.
|
|
// => error[E0004]: non-exhaustive patterns: ... not covered
|
|
//
|
|
// 4. OUT-OF-SET TARGET (E0599):
|
|
// in `on_unlock`, return `UnlockOutcome::Open`.
|
|
// => error[E0599]: no variant ... named `Open` found for enum `UnlockOutcome`
|
|
// ===========================================================================
|