Home

hfsm.dev API Cheat Sheet

Globals

Machine and MachineT<>

Using default settings:

using M = hfsm2::Machine;

Customizable version:

using M = hfsm2::MachineT<
              TContext,     // data shared between states and external code
              Config<>,     // optional: config, see below
              TPayload      // optional: transition payload
          >;

Config<>

hfsm2::Config<
    TUtility,               // optional: customizable Expected Utility Value type (default: float)
    NMaxPlanTasks,          // optional: max number of plans' entries across the entire FSM
                            //                   (default: 2x number of sub-states in all regions)
    NMaxSubstitutions = 4   // optional: max number of guard substitutions
>

Regions

Default Versions:

Type	Root	Region
Composite	M::Root<THeadState, TSubStates>	M::Composite<THeadState, TSubStates>
Resumable	M::ResumableRoot<THeadState, TSubStates>	M::Resumable<THeadState, TSubStates>
Utilitarian	M::UtilitarianRoot<THeadState, TSubStates>	M::Utilitarian<THeadState, TSubStates>
Orthogonal	M::OrthogonalRoot<THeadState, TSubStates>	M::Orthogonal<THeadState, TSubStates>

Headless Versions:

Type	Headless Root	Headless Region
Composite	M::PeerRoot<TSubStates>	M::CompositePeers<TSubStates>
Resumable	M::ResumablePeerRoot<TSubStates>	M::ResumablePeers<TSubStates>
Utilitarian	M::UtilitarianPeerRoot<TSubStates>	M::UtilitarianPeers<TSubStates>
Orthogonal	M::OrthogonalPeerRoot<TSubStates>	M::OrthogonalPeers<TSubStates>

FSM Stucture Declaration

#define S(s) struct s

using FSM = M::Root<S(..),
               ..
            >;

#undef S

Root<> (a.k.a. 'public FSM') API

Group	Methods
Inspect Structure	StateID stateId<TState>() RegionID regionId<TRegion>()
Query State Activity	bool isActive<TState>() bool isResumable<TState>() bool isScheduled<TState>()	bool isActive(StateID) bool isResumable(StateID) bool isScheduled(StateID)
Initiate Transitions	void changeTo<TState>() void restart<TState>() void resume<TState>() void utilize<TState>() void schedule<TState>()	void changeTo(StateID) void restart(StateID) void resume(StateID) void utilize(StateID) void schedule(StateID)
Initiate Transitions with Payloads	void changeTo<TState>(Payload&) void restart<TState>(Payload&) void resume<TState>(Payload&) void utilize<TState>(Payload&) void schedule<TState>(Payload&)	void changeTo(StateID, Payload&) void restart(StateID, Payload&) void resume(StateID, Payload&) void utilize(StateID, Payload&) void schedule(StateID, Payload&)
Operations on Payloads	void resetStateData<TState>() void setStateData<TState>(Payload&) bool isStateDataSet<TState>() const Payload* getStateData<TState>()	void resetStateData(StateID) void setStateData(StateID, Payload&) bool isStateDataSet(StateID) const Payload* getStateData(StateID)
Debug API	const MachineStructure& structure() const MachineActivity& activity()
Logger API	void attachLogger(LoggerInterface*)

States

Overridable M::State Methods

Group	Methods
Pre-Conditions	Config::Utility utility(const Control&)
Guards	void entryGuard(GuardControl&) void exitGuard(GuardControl&)
Transition Events	void enter(PlanControl&) void exit(PlanControl&)
Periodic Updates	void update(FullControl&)
Event Reactions	void react(const TEvent&, FullControl&)
Plan Events	void planSucceeded(FullControl&) void planFailed(FullControl&)

Additional Overridable Region Head M::State Methods

Group	Methods
Plan Events	void planSucceeded(FullControl&) void planFailed(FullControl&)

State Bases

Default:

struct UserState
    : FSM::State
{}

Inject shared code (see Injections below for more details)

struct UserState
    : FSM::StateT<TInjection1, TInjection2>
{}

Injections

struct UserInjection
    : FSM::Bare
{}

Overridable Injection Methods

Group	Methods
Guards	void preEntryGuard(Context&) void preExitGuard(Context&)
Bounds	void preEnter(Context&) void postExit(Context&)
Periodic Updates	void preUpdate(Context&)
Event Reactions	void preReact(const TEvent&, Context&)

Controls

Control Inheritance Graph

GuardControl -> FullControl -> PlanControl -> Control

Functional Overview

Type	Additional Functionality
Control	Inspect
PlanControl	Modify plans
FullControl	Issue transitions Succeed and fail plans
GuardControl	Cancel in-flight transitions

Control Interface

Used in:

• M::State::utility(Control&)

Group	Methods
Inspect Structure	StateID stateId<TState>() RegionID regionId<TRegion>()
Access Context	Context& _() Context& context()
Query State Activity	bool isActive<TState>() bool isResumable<TState>() bool isScheduled<TState>()	bool isActive(StateID) bool isResumable(StateID) bool isScheduled(StateID)
Inspect Own Plan	ConstPlan plan()
Inspect Plans	ConstPlan plan<TRegion>()	ConstPlan plan(RegionID)

Additional PlanControl Interface

Used in:

• void enter(PlanControl&)
• void exit(PlanControl&)

Group	Methods
Modify Own Plan	Plan plan()
Modify Plans	Plan plan<TRegion>()	Plan plan(RegionID)

Additional FullControl Interface

Used in:

• void update(FullControl&)
• void react(const TEvent&, FullControl&)
• void planSucceeded(FullControl&)
• void planFailed(FullControl&)

Group	Methods
Initiate Transitions	void changeTo<TState>() void restart<TState>() void resume<TState>() void utilize<TState>() void schedule<TState>()	void changeTo(StateID) void restart(StateID) void resume(StateID) void utilize(StateID) void schedule(StateID)
Succeed / Fail Plans	void succeed() void fail()

Additional GuardControl Interface

Used in:

• void entryGuard(GuardControl&)
• void exitGuard(GuardControl&)

Group	Methods
Cancel In-Flight Transitions	void cancel()

Plans

ConstPlan Interface

Group	Methods
Inspect Structure	StateID stateId<TState>() RegionID regionId<TRegion>()
Validity	explicit operator bool()

Plan Interface

Group	Methods
Clear	void clear()
Append Transition	void add<TOrigin, TDestination>()	void add(StateID origin, StateID destination)
Remove Transition by Index	void remove(LongIndex)