secs-gem/docs/35_state_machines_and_dispatch.md

35 — State machines and dispatch

← 34 Codec and SML | Back to index | Next: 36 Persistence, validation, metrics →

We have transport (chapter 33) delivering secs2::Messages (chapter 34) into the application. We have stores (chapter 32) holding the data. This chapter is the glue: how the Router dispatches by (stream, function), how state machines compose with stores, and how a Router handler typically looks.

---

gem::Router — the dispatch table

include/secsgem/gem/router.hpp:

class Router {
 public:
  using Handler = std::function<std::optional<s2::Message>(const s2::Message&)>;

  Router& on(uint8_t stream, uint8_t function, Handler h);
  Router& fallback(Handler h);

  std::optional<s2::Message> dispatch(const s2::Message& msg) const;
};

A std::map<{stream, function}, Handler>. Each handler:

• Takes a const s2::Message& (the inbound primary).
• Returns a std::optional<s2::Message> (the reply, or nullopt for fire-and-forget primaries).

That's it. No middleware, no decorator chain, no pre/post hooks. Just a typed dispatch.

Registering handlers

// apps/secs_server.cpp — sketch
auto router = std::make_shared<gem::Router>();

router->on(1, 1, [model](const auto& m) {
  // S1F1 Are You There — reply with model name + softrev.
  return messages::s1f2(model->device.mdln, model->device.softrev);
});

router->on(1, 3, [model](const auto& m) {
  // S1F3 — read SVID values.
  auto svid_list = messages::parse_s1f3(m.body());
  return messages::s1f4(model->svids.values(svid_list.value_or({})));
});

router->on(2, 41, [model](const auto& m) {
  // S2F41 Host Command.
  auto cmd = messages::parse_s2f41(m.body());
  auto ack = model->commands.dispatch(cmd->rcmd, cmd->params);
  return messages::s2f42(ack);
});

// ...one per S/F pair.  apps/secs_server.cpp registers ~50.

The examples/pvd_tool/main.cpp §6 register 51 handlers in ~460 lines. Each handler is a few lines: parse the body, mutate or read a store, build the reply.

What happens for unhandled primaries

// router.hpp dispatch()
auto it = handlers_.find({msg.stream, msg.function});
if (it != handlers_.end()) return it->second(msg);
if (fallback_) return fallback_(msg);
if (msg.reply_expected) return s2::Message(msg.stream, 0, false);  // SxF0 Abort
return std::nullopt;

Three cases:

1. Registered: handler runs.
2. Fallback installed: fallback runs.
3. Neither: if the message expects a reply, send SxF0 (Abort) per E5 convention. Otherwise silently drop.

S9 wiring

The transport layer (chapter 11) emits S9F3 / S9F5 for unhandled primaries. Router exposes the introspection:

bool has_handler(uint8_t stream, uint8_t function) const;
bool has_handler_for_stream(uint8_t stream) const;

And the wrapper that combines them with S9 emission:

template <typename EmitFn, typename HeaderProvider>
std::optional<s2::Message> dispatch_with_s9(
    EmitFn emit_s9, HeaderProvider header_provider,
    const s2::Message& msg) const {
  if (!has_handler(msg.stream, msg.function)) {
    if (auto mhead = header_provider()) {
      const uint8_t f = has_handler_for_stream(msg.stream) ? 5 : 3;
      emit_s9(f, *mhead);
    }
  }
  return dispatch(msg);
}

Used by Connection::on_data_message → Router::dispatch_with_s9, which calls back into Connection::emit_s9 for the actual S9 emission. Tested by tests/test_s9_fallback.cpp (2 cases — unknown stream → S9F3, unknown function in known stream → S9F5).

---

How a typical handler looks end-to-end

S2F41 Host Command is the most-touched message in production — worth tracing in full:

1. The codegen'd parser/builder

// build/generated/secsgem/gem/messages.hpp (auto-generated)
struct RemoteCommand {
  std::string rcmd;
  std::vector<std::pair<std::string, secs2::Item>> params;
};

inline std::optional<RemoteCommand> parse_s2f41(const secs2::Item& body) {
  // ...auto-generated body walker...
}

inline secs2::Message s2f42(uint8_t hcack, /* per-param acks */) {
  // ...auto-generated builder...
}

2. The Router registration

// apps/secs_server.cpp
router->on(2, 41, [model](const secs2::Message& m) {
  auto cmd = messages::parse_s2f41(m.body());
  if (!cmd) {
    // Body didn't parse — reply S2F42 with HCACK = 1 (invalid).
    return messages::s2f42(1, {});
  }
  auto outcome = model->commands.dispatch(cmd->rcmd, cmd->params);
  return messages::s2f42(static_cast<uint8_t>(outcome.ack), outcome.cpacks);
});

3. The store dispatch

// include/secsgem/gem/store/host_commands.hpp
class HostCommandRegistry {
 public:
  CommandOutcome dispatch(const std::string& rcmd, const ParamList& params) {
    auto it = commands_.find(rcmd);
    if (it == commands_.end()) return {HostCmdAck::InvalidCommand, ...};
    const auto& cmd = it->second;
    // Apply configured side effects: emit_ceid, set_alarm, …
    for (auto ceid : cmd.emit_ceids) on_emit_ceid_(ceid);
    for (auto alid : cmd.set_alarms) alarm_registry_->set(alid);
    return {cmd.default_ack, ...};
  }
};

4. The side-effect dispatcher

Steps in dispatch like on_emit_ceid_(ceid) call back into the EAP:

// Set up at startup:
model->commands.set_emit_ceid_handler([conn, model](uint32_t ceid) {
  if (!model->is_event_enabled(ceid)) return;
  auto reports = model->compose_reports_for(ceid);
  auto msg = build_s6f11(ceid, reports);
  conn->send_data(std::move(msg));
});

5. The wire

conn->send_data(s6f11) walks through secs2::encode → hsms::Frame::encode → async_write to the socket. Host sees the unsolicited S6F11.

---

The state-machine pattern

Every state machine in the codebase follows the same shape. Pick ControlStateMachine:

// include/secsgem/gem/control_state.hpp
class ControlStateMachine {
 public:
  ControlStateMachine(ControlTransitionTable table);

  ControlState state() const;

  // Apply an event; returns the transition row (if any).
  const ControlTransition* on_event(ControlEvent e);

  // Observer for transitions.
  using StateChangeHandler =
      std::function<void(ControlState from, ControlState to, ControlEvent)>;
  void set_state_change_handler(StateChangeHandler h);
};

Three properties:

1. Pure data table (ControlTransitionTable) decides what transitions exist.
2. Pure FSM (ControlStateMachine) applies events against the table, updates state, emits the change.
3. Observer pattern — the EAP registers a change handler that does the wire-level work (fire CEID, emit S6F11, log to metrics).

This pattern repeats for:

• ProcessJobStateMachine (E40)
• ControlJobStateMachine (E94)
• EptStateMachine (E116)
• ExceptionStateMachine (E5 §13)
• CarrierStateMachine (E87 — actually composes 3 sub-FSMs)
• LoadPortStateMachine (E87 — same)
• SubstrateStateMachine (E90 — same)
• ModuleStateMachine (E157)
• E84StateMachine (E84)
• CommunicationStateMachine (E30 §6.5)

Eleven FSMs. All follow the same shape. All testable in isolation without IO.

---

How FSM transitions cascade into CEIDs

A common need: "when PJ-1 transitions to Processing, fire CEID=ProcessStarted, which fires an S6F11 with linked reports."

The wiring is set up at startup in the EAP:

// apps/secs_server.cpp — sketch
model->process_jobs.set_state_change_handler(
    [conn, model](const std::string& pjid,
                  ProcessJobState from, ProcessJobState to,
                  ProcessJobEvent ev) {
      // Configured per-state CEID from data/equipment.yaml.
      auto ceid = ceid_for_pj_state(to);
      if (!ceid || !model->is_event_enabled(*ceid)) return;
      auto reports = model->compose_reports_for(*ceid);
      auto msg = build_s6f11(*ceid, reports);
      deliver_or_spool(*conn, *model, std::move(msg));
    });

deliver_or_spool is the spool-aware send: if the connection isn't SELECTED (or the spool is in transmit-disabled mode), the message queues into SpoolStore; otherwise it goes straight to the wire.

So the chain for "PJ-1 starts processing":

ProcessJobStore.apply(pjid, Start)
  → ProcessJobStateMachine.on_event(Start)
  → State: WaitingForStart → Processing
  → on_change handler fires
  → looks up CEID ProcessStarted
  → composes reports
  → builds S6F11 message
  → deliver_or_spool → connection or SpoolStore
  → on the wire (eventually)

Every step is independently testable. Tests at the wire level: tests/test_wire_ceid_emission.cpp (6 cases — every cascade from store mutation to socket bytes).

---

Where to go next

You've now seen everything that makes the runtime work. One chapter left in Part 3: the operational concerns — persistence, config validation, and metrics.

Next: → 36 Persistence, validation, metrics