Home

hfsm.dev API Cheat Sheet

Globals

Machine and MachineT<>

Using default settings:

using M = hfsm2::Machine;

Customizable version:

using M = hfsm2::MachineT<
              Config<...>,		// Configuration template, see below
          >;

Config<>

hfsm2::Config				// All the following are optional:
	::ContextT<T>			// Context, data shared between states and external code
	::RankT<T>				// Rank type, for weighted-random utility selector (default: int8_t)
	::UtilityT<T>			// Expected Utility Value type (default: float)
	::RandomT<T>			// PRNG for ranked weighted-random utility selector
							//	   (default: XoShiRo256Plus (64bit), XoShiRo128Plus (64bit))
	::PayloadT<T>			// Transition payload type
	::SubstitutionLimitN<N>	// Max number of transition substitutions in guards (default: 4)
	::TaskCapacityN<>		// Max number of tasks in all plans (default: 2x sub-state count)

Regions

Default Versions:

Type	Root	Region
Composite	M::Root<THead, TStates>	M::Composite<THead, TStates>
Resumable	M::ResumableRoot<THead, TStates>	M::Resumable<THead, TStates>
Utilitarian	M::UtilitarianRoot<THead, TStates>	M::Utilitarian<THead, TStates>
Random	M::RandomRoot<THead, TStates>	M::Random<THead, TStates>
Orthogonal	M::OrthogonalRoot<THead, TStates>	M::Orthogonal<THead, TStates>

Headless Versions:

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

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 randomize<TState>() void schedule<TState>()	void changeTo(StateID) void restart(StateID) void resume(StateID) void utilize(StateID) void randomize(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 randomize<TState>(Payload&) void schedule<TState>(Payload&)	void changeTo(StateID, Payload&) void restart(StateID, Payload&) void resume(StateID, Payload&) void utilize(StateID, Payload&) void randomize(StateID, Payload&) void schedule(StateID, Payload&)
Operations on Payloads	void resetStateData<TState>() void setStateData<TState>(Payload&) bool isStateDataSet<TState>() Payload* getStateData<TState>()	void resetStateData(StateID) void setStateData(StateID, Payload&) bool isStateDataSet(StateID) 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 randomize<TState>() void schedule<TState>()	void changeTo(StateID) void restart(StateID) void resume(StateID) void utilize(StateID) void randomize(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, StateID)
Remove Transition	void remove(LongIndex)