Hierarchical State Machine base class. More...

#include <qep.hpp>

Inheritance diagram for QHsm:

Collaboration diagram for QHsm:

Public Member Functions
virtual	~QHsm ()
	virtual destructor More...

virtual void	init (void const *const e, std::uint_fast8_t const qs_id)
	executes the top-most initial transition in QP::QHsm More...

virtual void	init (std::uint_fast8_t const qs_id)
	overloaded init(qs_id) More...

virtual void	dispatch (QEvt const *const e, std::uint_fast8_t const qs_id)
	Dispatches an event to QHsm. More...

bool	isIn (QStateHandler const s) noexcept
	Tests if a given state is part of the current active state configuration. More...

QStateHandler	state (void) const noexcept
	Obtain the current state (state handler function) More...

QStateHandler	childState (QStateHandler const parent) noexcept
	Obtain the current active child state of a given parent. More...

Static Public Member Functions
static QState	top (void const me, QEvt const const e) noexcept
	the top-state. More...

Static Public Attributes
static constexpr QState	Q_RET_SUPER {static_cast<QState>(0)}
	event passed to the superstate to handle More...

static constexpr QState	Q_RET_SUPER_SUB {static_cast<QState>(1)}
	event passed to submachine superstate More...

static constexpr QState	Q_RET_UNHANDLED {static_cast<QState>(2)}
	event unhandled due to a guard evaluating to 'false' More...

static constexpr QState	Q_RET_HANDLED {static_cast<QState>(3)}
	event handled (internal transition) More...

static constexpr QState	Q_RET_IGNORED {static_cast<QState>(4)}
	event silently ignored (bubbled up to top) More...

static constexpr QState	Q_RET_ENTRY {static_cast<QState>(5)}
	state entry action executed More...

static constexpr QState	Q_RET_EXIT {static_cast<QState>(6)}
	state exit action executed More...

static constexpr QState	Q_RET_NULL {static_cast<QState>(7)}
	return value without any effect More...

static constexpr QState	Q_RET_TRAN {static_cast<QState>(8)}
	regular transition taken More...

static constexpr QState	Q_RET_TRAN_INIT {static_cast<QState>(9)}
	initial transition taken More...

static constexpr QState	Q_RET_TRAN_EP {static_cast<QState>(10)}
	entry-point transition into a submachine More...

static constexpr QState	Q_RET_TRAN_HIST {static_cast<QState>(11)}
	transition to history of a given state More...

static constexpr QState	Q_RET_TRAN_XP {static_cast<QState>(12)}
	exit-point transition out of a submachine More...

Protected Types
enum	ReservedHsmSignals : QSignal { Q_ENTRY_SIG = 1 , Q_EXIT_SIG , Q_INIT_SIG }

Protected Member Functions
	QHsm (QStateHandler const initial) noexcept
	Protected constructor of QHsm. More...

QState	tran (QStateHandler const target) noexcept
	Helper function to specify a state transition. More...

QState	tran_hist (QStateHandler const hist) noexcept
	Helper function to specify a transition to history. More...

QState	super (QStateHandler const superstate) noexcept
	Helper function to specify the superstate of a given state. More...

QState	qm_tran (void const *const tatbl) noexcept
	Helper function to specify a regular state transition in a QM state-handler. More...

QState	qm_tran_hist (QMState const const hist, void const const tatbl) noexcept
	Helper function to specifiy a transition to history in a QM state-handler. More...

QState	qm_tran_init (void const *const tatbl) noexcept
	Helper function to specify an initial state transition in a QM state-handler. More...

QState	qm_tran_ep (void const *const tatbl) noexcept
	Helper function to specify a transition to an entry point to a submachine state in a QM state-handler. More...

QState	qm_tran_xp (QActionHandler const xp, void const *const tatbl) noexcept
	Helper function to specify a transition to an exit point from a submachine state in a QM state-handler. More...

QState	qm_entry (QMState const *const s) noexcept
	Helper function to specify a state entry in a QM state-handler. More...

QState	qm_exit (QMState const *const s) noexcept
	Helper function to specify a state exit in a QM state-handler. More...

virtual QStateHandler	getStateHandler () noexcept
	Get the current state handler of the HSM. More...

QState	qm_sm_exit (QMState const *const s) noexcept
	Helper function to specify a submachine exit in a QM state-handler. More...

QState	qm_super_sub (QMState const *const s) noexcept
	Helper function to call in a QM state-handler when it passes the event to the host submachine state to handle an event. More...

Private Member Functions
std::int_fast8_t	hsm_tran (QStateHandler(&path)[MAX_NEST_DEPTH_], std::uint_fast8_t const qs_id)
	internal helper function to take a transition in QP::QHsm More...

Private Attributes
QHsmAttr	m_state
	current active state (state-variable) More...

QHsmAttr	m_temp
	temporary: transition chain, target state, etc. More...

Static Private Attributes
static constexpr std::int_fast8_t	MAX_NEST_DEPTH_ {6}
	< maximum nesting depth of states in HSM More...

Friends
class	QMsm

class	QActive

class	QMActive

class	QF

class	QS

class	QXK

class	QXThread

class	QXMutex

class	QXSemaphore

class	QActiveDummy

Detailed Description

Hierarchical State Machine base class.

Description: QHsm represents a Hierarchical State Machine (HSM) with full support for hierarchical nesting of states, entry/exit actions, and initial transitions in any composite state. QHsm inherits QMsm without adding new attributes, so it takes the same amount of RAM as QMsm.
QHsm is also the base class for the QMsm state machine, which provides a superior efficiency, but requries the use of the QM modeling tool to generate code.

Note: QHsm is not intended to be instantiated directly, but rather serves as the base class for derivation of state machines in the application code.

Usage: The following example illustrates how to derive a state machine class from QHsm.
class Calc : public QHsm { // derived from QHsm

private:

double m_operand1;

double m_operand2;

char m_display[DISP_WIDTH + 1];

uint8_t m_len;

uint8_t m_opKey;

public:

Calc() // constructor

: QHsm(Calc)) { // superclass' constructor

}

protected:

Q_STATE_DECL(initial);

Q_STATE_DECL(on);

Q_STATE_DECL(error);

Q_STATE_DECL(ready);

Q_STATE_DECL(result);

Q_STATE_DECL(begin);

. . .

};

uint8_t
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: 16bit/stdint.h:29

QP::QHsm::QHsm
QHsm(QStateHandler const initial) noexcept
Protected constructor of QHsm.
Definition: qep_hsm.cpp:117

Q_STATE_DECL
#define Q_STATE_DECL(state_)
Macro to generate a declaration of a state-handler, state-caller and a state-object for a given state...
Definition: qep.hpp:619

Definition at line 269 of file qep.hpp.

Member Enumeration Documentation

◆ ReservedHsmSignals

enum ReservedHsmSignals : QSignal

protected

Enumerator
Q_ENTRY_SIG	signal for entry actions
Q_EXIT_SIG	signal for exit actions
Q_INIT_SIG	signal for nested initial transitions

Definition at line 371 of file qep.hpp.

Constructor & Destructor Documentation

◆ ~QHsm()

~QHsm ( )

virtual

virtual destructor

Description: Virtual destructor of the QHsm state machine and any of its subclasses.

Definition at line 126 of file qep_hsm.cpp.

◆ QHsm()

QHsm ( QStateHandler const initial )

explicitprotectednoexcept

Protected constructor of QHsm.

Description: Performs the first step of HSM initialization by assigning the initial pseudostate to the currently active state of the state machine.

Parameters

[in] initial pointer to the top-most initial state-handler function in the derived state machine

Definition at line 117 of file qep_hsm.cpp.

Member Function Documentation

◆ init() [1/2]

void init	(	void const *const	e,
		std::uint_fast8_t const	qs_id
	)

virtual

executes the top-most initial transition in QP::QHsm

Description: Executes the top-most initial transition in a HSM.

Parameters

[in]	e	pointer to an extra parameter (might be NULL)
[in]	qs_id	QS-id of this state machine (for QS local filter)

Note: Must be called exactly once before the QP::QHsm::dispatch().

Precondition: ctor must have been executed and initial tran NOT taken

Reimplemented in QMActive, QMsm, QXThread, QActiveDummy, and QTicker.

Definition at line 139 of file qep_hsm.cpp.

◆ init() [2/2]

virtual void init ( std::uint_fast8_t const qs_id )

inlinevirtual

overloaded init(qs_id)

Reimplemented in QMActive, QMsm, QXThread, QActiveDummy, and QTicker.

Definition at line 282 of file qep.hpp.

◆ dispatch()

void dispatch	(	QEvt const *const	e,
		std::uint_fast8_t const	qs_id
	)

virtual

Dispatches an event to QHsm.

Description: Dispatches an event for processing to a hierarchical state machine (HSM). The processing of an event represents one run-to-completion (RTC) step.

Parameters

[in]	e	pointer to the event to be dispatched to the HSM
[in]	qs_id	QS-id of this state machine (for QS local filter)

Note: This state machine must be initialized by calling QP::QHsm::init() exactly once before calling QP::QHsm::dispatch().

Precondition: the current state must be initialized and the state configuration must be stable

Reimplemented in QMActive, QMsm, QXThread, QActiveDummy, and QTicker.

Definition at line 242 of file qep_hsm.cpp.

◆ isIn()

bool isIn ( QStateHandler const s )

noexcept

Tests if a given state is part of the current active state configuration.

Description: Tests if a state machine derived from QHsm is-in a given state.

Note: For a HSM, to "be in a state" means also to be in a superstate of of the state.

Parameters

[in] s pointer to the state-handler function to be tested

Returns: 'true' if the HSM is in the state and 'false' otherwise

Precondition: state configuration must be stable

Definition at line 557 of file qep_hsm.cpp.

◆ state()

QStateHandler state ( void ) const

inlinenoexcept

Obtain the current state (state handler function)

Note: used in the QM code generation

Definition at line 296 of file qep.hpp.

◆ childState()

QStateHandler childState ( QStateHandler const parent )

noexcept

Obtain the current active child state of a given parent.

Note: used in the QM code generation

Description: Finds the child state of the given parent, such that this child state is an ancestor of the currently active state. The main purpose of this function is to support shallow history transitions in state machines derived from QHsm.

Parameters

[in] parent pointer to the state-handler function

Returns: the child of a given parent state, which is an ancestor of the currently active state

Note: this function is designed to be called during state transitions, so it does not necessarily start in a stable state configuration. However, the function establishes stable state configuration upon exit.

Postcondition: the child must be confirmed

Definition at line 600 of file qep_hsm.cpp.

◆ top()

QState top	(	void *const	me,
		QEvt const *const	e
	)

staticnoexcept

the top-state.

Description: The QP::QHsm::top() state handler is the ultimate root of state hierarchy in all HSMs derived from QP::QHsm.

Parameters

[in]	me	pointer to the HSM instance
[in]	e	pointer to the event to be dispatched to the HSM

Returns: Always returns Q_RET_IGNORED, which means that the top state ignores all events.

Note: The arguments to this state handler are not used. They are provided for conformance with the state-handler function signature QP::QStateHandler.

Definition at line 224 of file qep_hsm.cpp.

◆ tran()

QState tran ( QStateHandler const target )

inlineprotectednoexcept

Helper function to specify a state transition.

Definition at line 354 of file qep.hpp.

◆ tran_hist()

QState tran_hist ( QStateHandler const hist )

inlineprotectednoexcept

Helper function to specify a transition to history.

Definition at line 360 of file qep.hpp.

◆ super()

QState super ( QStateHandler const superstate )

inlineprotectednoexcept

Helper function to specify the superstate of a given state.

Definition at line 366 of file qep.hpp.

◆ qm_tran()

QState qm_tran ( void const *const tatbl )

inlineprotectednoexcept

Helper function to specify a regular state transition in a QM state-handler.

Definition at line 380 of file qep.hpp.

◆ qm_tran_hist()

QState qm_tran_hist	(	QMState const *const	hist,
		void const *const	tatbl
	)

inlineprotectednoexcept

Helper function to specifiy a transition to history in a QM state-handler.

Definition at line 387 of file qep.hpp.

◆ qm_tran_init()

QState qm_tran_init ( void const *const tatbl )

inlineprotectednoexcept

Helper function to specify an initial state transition in a QM state-handler.

Definition at line 397 of file qep.hpp.

◆ qm_tran_ep()

QState qm_tran_ep ( void const *const tatbl )

inlineprotectednoexcept

Helper function to specify a transition to an entry point to a submachine state in a QM state-handler.

Definition at line 404 of file qep.hpp.

◆ qm_tran_xp()

QState qm_tran_xp	(	QActionHandler const	xp,
		void const *const	tatbl
	)

inlineprotectednoexcept

Helper function to specify a transition to an exit point from a submachine state in a QM state-handler.

Definition at line 411 of file qep.hpp.

◆ qm_entry()

QState qm_entry ( QMState const *const s )

inlineprotectednoexcept

Helper function to specify a state entry in a QM state-handler.

Definition at line 421 of file qep.hpp.

◆ qm_exit()

QState qm_exit ( QMState const *const s )

inlineprotectednoexcept

Helper function to specify a state exit in a QM state-handler.

Definition at line 427 of file qep.hpp.

◆ getStateHandler()

QStateHandler getStateHandler ( )

protectedvirtualnoexcept

Get the current state handler of the HSM.

Reimplemented in QMActive, and QMsm.

Definition at line 539 of file qep_hsm.cpp.

◆ qm_sm_exit()

QState qm_sm_exit ( QMState const *const s )

inlineprotectednoexcept

Helper function to specify a submachine exit in a QM state-handler.

Definition at line 449 of file qep.hpp.

◆ qm_super_sub()

QState qm_super_sub ( QMState const *const s )

inlineprotectednoexcept

Helper function to call in a QM state-handler when it passes the event to the host submachine state to handle an event.

Definition at line 456 of file qep.hpp.

◆ hsm_tran()

std::int_fast8_t hsm_tran	(	QStateHandler(&)	path[MAX_NEST_DEPTH_],
		std::uint_fast8_t const	qs_id
	)

private

internal helper function to take a transition in QP::QHsm

Description: helper function to execute transition sequence in a hierarchical state machine (HSM).

Parameters

[in,out]	path	array of pointers to state-handler functions to execute the entry actions
[in]	qs_id	QS-id of this state machine (for QS local filter)

Returns: the depth of the entry path stored in the path parameter. /

Definition at line 404 of file qep_hsm.cpp.

Friends And Related Function Documentation

◆ QMsm

friend class QMsm

friend

Definition at line 469 of file qep.hpp.

◆ QActive

friend class QActive

friend

Definition at line 470 of file qep.hpp.

◆ QMActive

friend class QMActive

friend

Definition at line 471 of file qep.hpp.

◆ QF

friend class QF

friend

Definition at line 472 of file qep.hpp.

◆ QS

friend class QS

friend

Definition at line 473 of file qep.hpp.

◆ QXK

friend class QXK

friend

Definition at line 474 of file qep.hpp.

◆ QXThread

friend class QXThread

friend

Definition at line 475 of file qep.hpp.

◆ QXMutex

friend class QXMutex

friend

Definition at line 476 of file qep.hpp.

◆ QXSemaphore

friend class QXSemaphore

friend

Definition at line 477 of file qep.hpp.

◆ QActiveDummy

friend class QActiveDummy

friend

Definition at line 479 of file qep.hpp.

Field Documentation

◆ m_state

QHsmAttr m_state

private

current active state (state-variable)

Definition at line 270 of file qep.hpp.

◆ m_temp

QHsmAttr m_temp

private

temporary: transition chain, target state, etc.

Definition at line 271 of file qep.hpp.

◆ Q_RET_SUPER

constexpr QState Q_RET_SUPER {static_cast<QState>(0)}

staticconstexpr

event passed to the superstate to handle

Definition at line 314 of file qep.hpp.

◆ Q_RET_SUPER_SUB

constexpr QState Q_RET_SUPER_SUB {static_cast<QState>(1)}

staticconstexpr

event passed to submachine superstate

Definition at line 317 of file qep.hpp.

◆ Q_RET_UNHANDLED

constexpr QState Q_RET_UNHANDLED {static_cast<QState>(2)}

staticconstexpr

event unhandled due to a guard evaluating to 'false'

Definition at line 320 of file qep.hpp.

◆ Q_RET_HANDLED

constexpr QState Q_RET_HANDLED {static_cast<QState>(3)}

staticconstexpr

event handled (internal transition)

Definition at line 323 of file qep.hpp.

◆ Q_RET_IGNORED

constexpr QState Q_RET_IGNORED {static_cast<QState>(4)}

staticconstexpr

event silently ignored (bubbled up to top)

Definition at line 326 of file qep.hpp.

◆ Q_RET_ENTRY

constexpr QState Q_RET_ENTRY {static_cast<QState>(5)}

staticconstexpr

state entry action executed

Definition at line 329 of file qep.hpp.

◆ Q_RET_EXIT

constexpr QState Q_RET_EXIT {static_cast<QState>(6)}

staticconstexpr

state exit action executed

Definition at line 332 of file qep.hpp.

◆ Q_RET_NULL

constexpr QState Q_RET_NULL {static_cast<QState>(7)}

staticconstexpr

return value without any effect

Definition at line 335 of file qep.hpp.

◆ Q_RET_TRAN

constexpr QState Q_RET_TRAN {static_cast<QState>(8)}

staticconstexpr

regular transition taken

Definition at line 338 of file qep.hpp.

◆ Q_RET_TRAN_INIT

constexpr QState Q_RET_TRAN_INIT {static_cast<QState>(9)}

staticconstexpr

initial transition taken

Definition at line 341 of file qep.hpp.

◆ Q_RET_TRAN_EP

constexpr QState Q_RET_TRAN_EP {static_cast<QState>(10)}

staticconstexpr

entry-point transition into a submachine

Definition at line 344 of file qep.hpp.

◆ Q_RET_TRAN_HIST

constexpr QState Q_RET_TRAN_HIST {static_cast<QState>(11)}

staticconstexpr

transition to history of a given state

Definition at line 347 of file qep.hpp.

◆ Q_RET_TRAN_XP

constexpr QState Q_RET_TRAN_XP {static_cast<QState>(12)}

staticconstexpr

exit-point transition out of a submachine

Definition at line 350 of file qep.hpp.

◆ MAX_NEST_DEPTH_

constexpr std::int_fast8_t MAX_NEST_DEPTH_ {6}

staticconstexprprivate

< maximum nesting depth of states in HSM

Definition at line 463 of file qep.hpp.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ ReservedHsmSignals

Constructor & Destructor Documentation

◆ ~QHsm()

◆ QHsm()

Member Function Documentation

◆ init() [1/2]

◆ init() [2/2]

◆ dispatch()

◆ isIn()

◆ state()

◆ childState()

◆ top()

◆ tran()

◆ tran_hist()

◆ super()

◆ qm_tran()

◆ qm_tran_hist()

◆ qm_tran_init()

◆ qm_tran_ep()

◆ qm_tran_xp()

◆ qm_entry()

◆ qm_exit()

◆ getStateHandler()

◆ qm_sm_exit()

◆ qm_super_sub()

◆ hsm_tran()

Friends And Related Function Documentation

◆ QMsm

◆ QActive

◆ QMActive

◆ QF

◆ QS

◆ QXK

◆ QXThread

◆ QXMutex

◆ QXSemaphore

◆ QActiveDummy

Field Documentation

◆ m_state

◆ m_temp

◆ Q_RET_SUPER

◆ Q_RET_SUPER_SUB

◆ Q_RET_UNHANDLED

◆ Q_RET_HANDLED

◆ Q_RET_IGNORED

◆ Q_RET_ENTRY

◆ Q_RET_EXIT

◆ Q_RET_NULL

◆ Q_RET_TRAN

◆ Q_RET_TRAN_INIT

◆ Q_RET_TRAN_EP

◆ Q_RET_TRAN_HIST

◆ Q_RET_TRAN_XP

◆ MAX_NEST_DEPTH_