fsm.hpp File Reference

Header-only C++20 hierarchical, table-driven finite state machine. More...

#include <cassert>
#include <array>
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <type_traits>

Include dependency graph for fsm.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	fsm::result< State, Event, Reason >
	Dispatch verdict: what happened, where, and why. More...
struct	fsm::any_t
	Tag type for fsm::any. More...
struct	fsm::internal_t
	Tag type for fsm::internal. More...
struct	fsm::no_timeout_t
	Tag type for fsm::no_timeout. More...
struct	fsm::event_tag< E >
	Tag carrying an event as a compile-time value. More...
struct	fsm::from_spec< State >
	Row source: a concrete state or the fsm::any wildcard. More...
struct	fsm::on_spec< Event >
	Row trigger event, with poison default for omitted .on. More...
struct	fsm::target< State, Reason >
	Row target: external transition, internal handling, or refusal. More...
struct	fsm::state_id< State >
	State identifier for a state_spec, with poison default. More...
struct	fsm::root_t
	Tag type for fsm::root. More...
struct	fsm::parent_spec< State >
	Parent link — a mandatory column: fsm::root or fsm::child_of(P). More...
struct	fsm::initial_spec< State >
	Initial-child declaration for composite states. More...
struct	fsm::timeout_spec< Event >
	Per-state deadline declaration — a mandatory column. More...
struct	fsm::row< State, Event, Context, Payload, Reason >
	One transition-table row: {from, on, when, then, to}. More...
struct	fsm::state_spec< State, Event, Context >
	One state's specification: hierarchy links, actions, deadline. More...
struct	fsm::observer< State, Event, Reason >
	Runtime-attachable debug observer: plain nullable function pointers. More...
class	fsm::machine< Traits >
	The state machine engine interpreting a Traits' constexpr tables. More...

Namespaces
namespace	fsm

Macros
#define	FSM_ENABLE_PAYLOAD_CHECKS   1
#define	FSM_PAYLOAD_ASSERT(cond)   assert(cond)
#define	FSM_ENABLE_DEADLINE_CHECKS   1
#define	FSM_DEADLINE_ASSERT(cond)   assert(cond)
Library version
#define	FSM_VERSION_MAJOR   0
#define	FSM_VERSION_MINOR   4
#define	FSM_VERSION_PATCH   1

Enumerations
enum class	fsm::status : uint8_t {   fsm::transitioned , fsm::handled_internally , fsm::refused_by_row , fsm::refused_guard ,   fsm::unhandled , fsm::refused_reentrant , fsm::not_started }
	Verdict category returned by machine::dispatch(). More...
enum class	fsm::from_kind : uint8_t { fsm::unspecified , fsm::any , fsm::state }
	Kinds for row::from. unspecified is the poison default. More...
enum class	fsm::on_kind : uint8_t { fsm::unspecified , fsm::event }
	Kinds for row::on. unspecified is the poison default. More...
enum class	fsm::target_kind : uint8_t { fsm::unspecified , fsm::to , fsm::internal_ , fsm::refuse_ }
	Kinds for row::to. unspecified is the poison default. More...
enum class	fsm::id_kind : uint8_t { fsm::unspecified , fsm::state }
	Kinds for state_spec::state. unspecified is the poison default. More...
enum class	fsm::parent_kind : uint8_t { fsm::unspecified , fsm::root , fsm::child }
	Kinds for state_spec::parent. unspecified is the poison default. More...
enum class	fsm::initial_kind : uint8_t { fsm::leaf , fsm::start_at }
	Kinds for state_spec::initial. Default is leaf (no children). More...
enum class	fsm::timeout_kind : uint8_t { fsm::unspecified , fsm::none , fsm::after_ , fsm::after_dyn_ }
	Kinds for state_spec::deadline. unspecified is the poison default. More...

Functions
template<class State , class Event , class Reason >
constexpr bool	fsm::accepted (const result< State, Event, Reason > &r)
	True when the event was acted on (transitioned or handled internally).
template<class State >
constexpr detail::to_t< State >	fsm::to (State s)
	Make an external-transition target.
template<class Reason >
constexpr detail::refuse_t< Reason >	fsm::refuse (Reason r)
	Make a declarative refusal target carrying a reason.
template<class State >
constexpr parent_spec< State >	fsm::child_of (State s)
	Declare a state's parent in the hierarchy.
template<class State >
constexpr initial_spec< State >	fsm::start_at (State s)
	Declare the child entered when a composite state is targeted.
template<class Event >
constexpr timeout_spec< Event >	fsm::after (uint32_t ms, Event e)
	Declare "dispatch @p e after @p ms milliseconds in this state".
template<class Event >
constexpr timeout_spec< Event >	fsm::after_dyn (Event e)
	Declare a dynamic deadline: duration read from the context at entry time instead of the table.

Variables
constexpr uint16_t	fsm::no_row = 0xFFFF
	Sentinel row index meaning "no table row was involved".
constexpr any_t	fsm::any {}
	Wildcard row source: matches any state, after all ancestor levels.
constexpr internal_t	fsm::internal {}
	Row target: handle the event (run the action) without exit/entry.
constexpr no_timeout_t	fsm::no_timeout {}
	State deadline declaration: this state has no timeout (explicitly).
constexpr root_t	fsm::root {}
	Parent declaration: this state is a hierarchy root (no parent).

Detailed Description

Header-only C++20 hierarchical, table-driven finite state machine.

Zero heap allocation, zero virtual functions, compiles with -fno-exceptions -fno-rtti. A machine is defined by two constexpr tables (transition rows and state specs) inside a user Traits struct, and validated at compile time when fsm::machine<Traits> is instantiated.

Copyright

MIT License. Copyright (c) 2026 Justin justi.nosp@m.n@dy.nosp@m.nam.a.nosp@m.c

Macro Definition Documentation

FSM_DEADLINE_ASSERT

#define FSM_DEADLINE_ASSERT

(

cond

)

assert(cond)

FSM_ENABLE_DEADLINE_CHECKS

#define FSM_ENABLE_DEADLINE_CHECKS   1

FSM_ENABLE_PAYLOAD_CHECKS

#define FSM_ENABLE_PAYLOAD_CHECKS   1

FSM_PAYLOAD_ASSERT

#define FSM_PAYLOAD_ASSERT

(

cond

)

assert(cond)

FSM_VERSION_MAJOR

#define FSM_VERSION_MAJOR   0

FSM_VERSION_MINOR

#define FSM_VERSION_MINOR   4

FSM_VERSION_PATCH

#define FSM_VERSION_PATCH   1