-
Notifications
You must be signed in to change notification settings - Fork 12
API
Developers are supposed to utilize template class HierarchicalStateMachine to use HSM in their projects. The simplest approach is to create your own handler class that derives from HierarchicalStateMachine:
class MyHandler: protected HierarchicalStateMachine<MyStates, MyEvents, MyHandler>
{ ... };From here it becomes possible to utilize provided API to configure HSM structure.
- (constructor)
- (destructor)
- initialize
- registerState
- registerSubstate
- registerTransition
- getCurrentState
- transitionEx
- transition
- transitionWithQueueClear
- isTransitionPossible
| Name | Type | Default | Description |
|---|---|---|---|
| initialState | const HsmStateEnum | Specifies initial state for HSM |
Can be created on any thread without limitations, but in general it's recommented to do it on the same thread where dispatcher was created.
Since it uses unregisterEventHandler() method of event dispatcher it depends on it's implementation. Some dispatchers require their methods to be called from a single thread. General recomendation would be to create and destroy HSM from a single thread.
Registers HSM object with provided event dispatcher. If dispatcher is not running yet it will be automatically started. All HSM callbacks will be executed in the context provided by dispatcher.
| Name | Type | Default | Description |
|---|---|---|---|
| dispatcher | const std::shared_ptr& | event dispatcher to use for HSM transitions mechanism |
bool: Returns FALSE in case of an error during HSM initialization. Possible reasons could be:
- dispatcher not provided
- failed to start dispatcher
Not thread safe. Recommended to call from the same thread where dispatcher was created.
Registers HSM state and its handler callbacks. Does nothing if no callbacks are provided.
Note: if you want to use HSM_ENABLE_SAFE_STRUCTURE flag to validate HSM structure then all states must be registered (even if they dont have callbacks).
Prototype 1
| Name | Type | Default | Description |
|---|---|---|---|
| state | const HsmStateEnum | state to register | |
| handler | HsmHandlerClass* | nullptr | object that implements callbacks |
| onStateChanged | HsmStateChangedCallbackPtr_t | nullptr | "state changed" callback |
| onEntering | HsmStateEnterCallbackPtr_t | nullptr | "entering state" callback |
| onExiting | HsmStateExitCallbackPtr_t | nullptr | "exiting state" callback |
Prototype 2
| Name | Type | Default | Description |
|---|---|---|---|
| state | const HsmStateEnum | state to register | |
| onStateChanged | HsmStateChangedCallback_t | nullptr | "state changed" callback |
| onEntering | HsmStateEnterCallback_t | nullptr | "entering state" callback |
| onExiting | HsmStateExitCallback_t | nullptr | "exiting state" callback |
Not thread safe.
Registers a state as a substate. This imposes a couple of restrictions:
- each parent state must have only one entry point
- first call to this method must have isEntryPoint parameter set to true (per each parent)
- if multiple entry points are specified only the last one will be applied
- callbacks provided in registerState() for parent states will be ignored
- single state can't be added as a substate to multiple parents
- state can't be added as a substate multiple times
Provides additional structure validation if HSM_ENABLE_SAFE_STRUCTURE flag is set.
| Name | Type | Default | Description |
|---|---|---|---|
| parent | const HsmStateEnum | parent state where a substate should be added | |
| substate | const HsmStateEnum | state which should be registered as a substate | |
| isEntryPoint | const bool | false | substate will be treated as an entry point if TRUE is specified |
bool: Returns TRUE if substate registration was successful.
Not thread safe.
Registers transition between states.
Prototype 1
| Name | Type | Default | Description |
|---|---|---|---|
| from | const HsmStateEnum | state from which transition initiates | |
| to | const HsmStateEnum | state to which transition leads | |
| onEvent | const HsmEventEnum | event that should trigger transition | |
| handler | HsmHandlerClass* | nullptr | object that implements callbacks |
| transitionCallback | HsmTransitionCallbackPtr_t | nullptr | callback that will be triggered during transition |
| conditionCallback | HsmTransitionConditionCallbackPtr_t | nullptr | callback that will be triggered before transition to check if it's allowed |
Prototype 2
| Name | Type | Default | Description |
|---|---|---|---|
| from | const HsmStateEnum | state from which transition initiates | |
| to | const HsmStateEnum | state to which transition leads | |
| onEvent | const HsmEventEnum | event that should trigger transition | |
| transitionCallback | HsmTransitionCallback_t | nullptr | callback that will be triggered during transition |
| conditionCallback | HsmTransitionConditionCallback_t | nullptr | callback that will be triggered before transition to check if it's allowed |
Not thread safe.
Returns current HSM state.
HsmStateEnum: current HSM state
Thread safe.
Sends event to HSM and tries to trigger a transition.
| Name | Type | Default | Description |
|---|---|---|---|
| event | const HsmEventEnum | event to send to HSM | |
| clearQueue | const bool | clear all pending events before sending a new event | |
| sync | const bool | block execution and wait for transition to finish | |
| args | Args... | optional arguments to pass to callbacks |
bool: for async transitions always returns TRUE; for SYNC transitions returns TRUE only if transition was successfully finished, otherwise returns FALSE.
Safe to call from any thread.
Simple async transition. Wrapper over transitionEx().
| Name | Type | Default | Description |
|---|---|---|---|
| event | const HsmEventEnum | event to send to HSM | |
| args | Args... | optional arguments to pass to callbacks |
Safe to call from any thread.
Async transition with clearing pending events queue. Wrapper over transitionEx().
| Name | Type | Default | Description |
|---|---|---|---|
| event | const HsmEventEnum | event to send to HSM | |
| args | Args... | optional arguments to pass to callbacks |
Safe to call from any thread.
Checks if sending event will result in any transitions from current HSM state. Method just simulates a transition and does not modify anything in an HSM. Note: only transitions conditionCallback will be triggered. Other handlers like state callbacks will not be invoked.
| Name | Type | Default | Description |
|---|---|---|---|
| event | const HsmEventEnum | event to send to HSM | |
| args | Args... | optional arguments to pass to callbacks |
bool: returns TRUE if transition is possible
Safe to call from any thread.