Skip to content

Home

Jump to bottom
Andrew Gresyk edited this page Jun 3, 2019 · 18 revisions

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<THead, TStates> M::Composite<THead, TStates>
Resumable M::ResumableRoot<THead, TStates> M::Resumable<THead, TStates>
Utilitarian M::UtilitarianRoot<THead, TStates> M::Utilitarian<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>
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 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>()
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
Guards void entryGuard(GuardControl&)
void exitGuard(GuardControl&)
Transition Events void enter(PlanControl&)
void reenter(PlanControl&)
void exit(PlanControl&)
Periodic Updates void update(FullControl&)
Event Reactions void react(const TEvent&, FullControl&)

Additional Overridable Region Head M::State Methods

Group Methods
Utility Query Config::Utility utility(const Control&)
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::Injection
{}

Overridable Injection Methods

Group Methods
Guards void preEntryGuard(Context&)
void preExitGuard(Context&)
Bounds void preEnter(Context&)
void preReenter(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 State::enter(PlanControl&)
  • void State::reenter(PlanControl&)
  • void State::exit(PlanControl&)
Group Methods
Modify Own Plan Plan plan()
Modify Plans Plan plan<TRegion>() Plan plan(RegionID)

Additional FullControl Interface

Used in:

  • void State::update(FullControl&)
  • void State::react(const TEvent&, FullControl&)
  • void State::planSucceeded(FullControl&)
  • void State::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 State::entryGuard(GuardControl&)
  • void State::exitGuard(GuardControl&)
Group Methods
Query State Changes bool isPendingChange<TState>()
bool isPendingEnter<TState>()
bool isPendingExit<TState>() 		bool isPendingChange(StateID)
bool isPendingEnter(StateID)
bool isPendingExit(StateID)
Query In-Flight Transitions Requests& pendingTransitions()
Cancel In-Flight Transitions void cancelPendingTransitions()

Plans

ConstPlan Interface

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

Plan Interface

Group Methods
Clear void clear()
Remove
Transition		 void remove(LongIndex)

Plan Transition Interface

Queue a transition to destination state once origin state invokes succeed().

Group Methods
Change TaskIndex change<TOrigin, TDestination>() TaskIndex change<TOrigin>(StateID) TaskIndex change(StateID, StateID)
Restart TaskIndex restart<TOrigin, TDestination>() TaskIndex restart<TOrigin>(StateID) TaskIndex restart(StateID, StateID)
Resume TaskIndex resume<TOrigin, TDestination>() TaskIndex resume<TOrigin>(StateID) TaskIndex resume(StateID, StateID)
Utilize TaskIndex utilize<TOrigin, TDestination>() TaskIndex utilize<TOrigin>(StateID) TaskIndex utilize(StateID, StateID)
Schedule TaskIndex schedule<TOrigin, TDestination>() TaskIndex schedule<TOrigin>(StateID) TaskIndex schedule(StateID, StateID)

Overview

Configuration

Basic Features

Advanced Features

Typical Usage Scenarios

Legacy Pages

Clone this wiki locally