Self-Hosted C++ State Machine Libraries: Boost.SML vs tinyfsm vs HFSM2

Introduction

State machines are one of the most fundamental design patterns in software engineering. Whether you’re building a game entity behavior system, a network protocol parser, a UI navigation controller, or an embedded device firmware, you need reliable state management. In C++, several header-only libraries make this possible with compile-time guarantees and zero runtime overhead.

This article compares three modern C++ state machine libraries — Boost.SML, tinyfsm, and HFSM2 — examining their API design, performance characteristics, and ideal use cases. All three are header-only, require no external dependencies beyond a C++11/14/17 compiler, and are actively maintained.

Comparison Table

Boost.SML: The Compile-Time Powerhouse

Boost.SML (State Machine Language) by Kris Jusiak takes a unique approach — the entire state machine is defined as a C++ expression using a domain-specific language embedded in template parameters. The compiler validates all transitions, states, and events at compile time, meaning you cannot write an invalid state machine.

Installation

Boost.SML is a single header. Download it directly or use CMake FetchContent:

1
2
3
4
5
6
7
8
9

# CMakeLists.txt
include(FetchContent)
FetchContent_Declare(
  sml
  GIT_REPOSITORY https://github.com/boost-ext/sml.git
  GIT_TAG v1.1.11
)
FetchContent_MakeAvailable(sml)
target_link_libraries(myapp PRIVATE sml)

Basic Usage: Traffic Light Controller

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

#include <boost/sml.hpp>
#include <cassert>

namespace sml = boost::sml;

// Events
struct turn_green {};
struct turn_yellow {};
struct turn_red {};

// States
struct red {};
struct green {};
struct yellow {};

// Guards and actions
auto is_safe = [] { return true; };
auto start_timer = [] { /* start countdown */ };

// Transition table — compile-time verified
struct traffic_light {
  auto operator()() const {
    using namespace sml;
    return make_transition_table(
      *state<red>    + event<turn_green>  [is_safe] / start_timer = state<green>,
       state<green>  + event<turn_yellow>           / start_timer = state<yellow>,
       state<yellow> + event<turn_red>              / start_timer = state<red>
    );
  }
};

int main() {
  sml::sm<traffic_light> sm;
  assert(sm.is(state<red>));
  sm.process_event(turn_green{});
  assert(sm.is(state<green>));
}

The key strength of Boost.SML is the transition table — it reads like a specification document but is fully compiled. Any missing transition or duplicate event handler is caught at build time.

Hierarchical States

Boost.SML supports composite (nested) states with automatic event propagation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

auto composite_example = [] {
  using namespace sml;
  return make_transition_table(
    // Parent state "idle" with sub-states
    *state<idle> = state<idle_sub1>,
     state<idle_sub1> + event<next> = state<idle_sub2>,
    // Exit from any sub-state of "idle"
     state<idle>   + event<activate> = state<active>
  );
};

tinyfsm: Simplicity for Embedded Systems

tinyfsm by Axel Burri takes the opposite approach — rather than a DSL, it uses straightforward C++ class inheritance. Each state is a class, and transitions are method calls. This simplicity makes it ideal for embedded systems where code clarity and minimal template overhead are priorities.

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

#include <tinyfsm.hpp>

// Events
struct SwitchEvent : tinyfsm::Event {};

// Forward declare states
struct Off;
struct On;

// State machine definition
struct LightSwitch : tinyfsm::Fsm<LightSwitch> {
  virtual void react(SwitchEvent const &) {}
  virtual void entry() {}
  void exit() {}

  void react_default() { /* handle unexpected events */ }
};

// States
struct Off : LightSwitch {
  void entry() override { /* LED off */ }
  void react(SwitchEvent const &) override { transit<On>(); }
};

struct On : LightSwitch {
  void entry() override { /* LED on */ }
  void react(SwitchEvent const &) override { transit<Off>(); }
};

// Register states
FSM_INITIAL_STATE(LightSwitch, Off)

int main() {
  LightSwitch::start();
  LightSwitch::dispatch(SwitchEvent()); // Off -> On
  LightSwitch::dispatch(SwitchEvent()); // On -> Off
}

tinyfsm shines in constrained environments — the inheritance-based model is instantly recognizable to any C++ developer and produces minimal binary size. It includes a built-in mutex for thread-safe dispatch, something the other two libraries leave to the user.

Why Choose tinyfsm?

• Zero learning curve — if you understand C++ inheritance, you understand tinyfsm
• ARM/AVR friendly — compiles cleanly on bare-metal toolchains (gcc-arm-none-eabi, avr-gcc)
• Thread-safe out of the box — optional mutex guarding on dispatch()
• Small binary footprint — typically under 2KB for simple machines

HFSM2: Hierarchical State Machines Done Right

HFSM2 by Andrew Gresyk is the most feature-rich of the three. It supports the full UML statechart specification including hierarchical states, orthogonal regions, history states, and deferred events. The API uses a fluent builder pattern that reads like a configuration file.

Defining a Hierarchical State Machine

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

#include <hfsm2/machine.hpp>

// State machine with parent-child hierarchy
using M = hfsm2::MachineT<hfsm2::Config::ContextT<MyContext>>;

struct MyContext {
  int counter = 0;
  bool flag = false;
};

int main() {
  MyContext ctx;
  M::Instance machine(ctx);
  machine.update();      // Process pending transitions
  machine.immediate();   // Handle immediate transitions
}

HFSM2’s killer features are orthogonal regions (multiple concurrent state machines within the same machine) and comprehensive debugging tools including PlantUML export for visualizing your statechart:

1
2
3
4

// Export to PlantUML for documentation
hfsm2::LoggerInterface logger;
machine.visit(logger);
logger.toPlantUML("statechart.puml");

Performance Benchmarks

Benchmarks on a Raspberry Pi 4 (ARM Cortex-A72 @ 1.8GHz) dispatching 1 million events:

While a manual switch statement is still fastest, SML and HFSM2 come remarkably close while adding compile-time safety guarantees impossible with raw code. For most applications, the 10-20% overhead versus raw switch is negligible compared to the correctness guarantees.

Choosing the Right Library

• Boost.SML: Choose when you want maximum compile-time safety and your team is comfortable with template metaprogramming. The DSL transition table doubles as documentation. Best for application-level state machines (network protocols, UI controllers, game logic).

• tinyfsm: Choose for embedded projects where simplicity, small binary size, and wide compiler compatibility matter more than feature richness. The inheritance-based API is the easiest to teach. Best for IoT devices, motor controllers, and sensor systems.

• HFSM2: Choose when you need the full UML statechart feature set — hierarchical states, orthogonal regions, and history. The PlantUML export makes it excellent for projects where state machines must be documented alongside the codebase. Best for complex embedded systems, robotics, and industrial automation.

All three libraries are free, open source (Boost Software License / MIT), and production-tested. For related reading on C++ design patterns, see our guide to template metaprogramming libraries and compile-time programming techniques. If you’re exploring broader software architecture patterns, our C++ variant and sum type libraries comparison covers complementary type-safe design approaches.

FAQ

When should I use a state machine library instead of a switch-case statement?

Use a library when your state machine has more than 5 states or 10 transitions. Manual switch statements become unmaintainable quickly — adding a new state requires touching multiple case blocks. State machine libraries centralize the transition logic and prevent incorrect transitions at compile time.

Can these libraries run on ESP32 or Arduino?

Yes. All three libraries are header-only and compile fine on ESP32 (ESP-IDF and Arduino framework) and other ARM Cortex-M microcontrollers. tinyfsm is explicitly designed with embedded constraints in mind and has the smallest binary footprint. For Arduino, both Boost.SML and tinyfsm work without modification.

What is the difference between a finite state machine (FSM) and a hierarchical state machine (HSM)?

An FSM has flat states — every state is at the same level. An HSM allows states to contain sub-states, forming a tree. For example, a “Combat” parent state might contain “Attacking”, “Defending”, and “Fleeing” sub-states. Events propagate from the innermost state upward. HSMs dramatically reduce duplicate transitions. Boost.SML and HFSM2 support HSMs; tinyfsm is FSM-only.

How do I debug a state machine that behaves unexpectedly?

Boost.SML provides sml::sm<Machine, sml::logger<MyLogger>> for tracing every event dispatch. HFSM2 exports to PlantUML for visual inspection. For tinyfsm, add logging to entry() and react() methods. All three support injecting mock events for unit testing.

Are these libraries safe for real-time systems?

Boost.SML and HFSM2 allocate no dynamic memory during event dispatch (all states are compile-time instantiated), making them suitable for soft real-time systems. tinyfsm uses only static allocation and is safe for hard real-time embedded systems. None of the three throw exceptions during normal dispatch.

How do these compare to state machine frameworks in other languages?

Unlike JavaScript libraries like XState (which interpret statechart JSON at runtime), Boost.SML validates the entire machine at compile time — you get syntax errors before running. This eliminates an entire class of runtime bugs. C++ state machine libraries achieve zero-overhead abstractions through template metaprogramming, something dynamic languages cannot replicate.

💰 想测试你的市场判断力？我用 Polymarket 做预测市场交易——这是全球最大的预测市场平台，从大选结果到技术监管时间线，什么都可以押注。和赌博不同，这是真正的信息市场：你懂的信息越多，胜率越高。我靠预测技术相关事件的走向已经赚了不少。用我的邀请链接注册：Polymarket.com