Hierarchical State Machine base class. More...

#include <qep.hpp>

Inheritance diagram for QHsm:

Public Member Functions
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 handler. 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)
	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	QHsmDummy

class	QActiveDummy

Detailed Description

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 is also the base class for the QMsm state machine, which provides a superior efficiency, but requires 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 QP::QHsm { // inherits QP::QHsm

private:

double m_operand1;

double m_operand2;

char m_display[DISP_WIDTH + 1];

std::uint8_t m_len;

std::uint8_t m_opKey;

public:

Calc() // constructor

: QP::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);

. . .

};

QP::QHsm
Hierarchical State Machine base class.
Definition: qep.hpp:258

QP
namespace associated with the QP/C++ framework
Definition: exa_native.dox:1

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:805

Definition at line 258 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 436 of file qep.hpp.

Constructor & Destructor Documentation

◆ QHsm()

QHsm ( QStateHandler const initial )

explicitprotectednoexcept

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

Traceability:: traces to: RQP103

Definition at line 109 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

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().

Traceability:

traces to: RQP103

traces to: RQP120I

traces to: RQP120D

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

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

Definition at line 115 of file qep_hsm.cpp.

◆ init() [2/2]

virtual void init ( std::uint_fast8_t const qs_id )

inlinevirtual

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

Definition at line 286 of file qep.hpp.

◆ dispatch()

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

virtual

Description: Dispatches an event for processing to a hierarchical state machine. 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().

Traceability:

traces to: RQP103

traces to: RQP120A

traces to: RQP120B

traces to: RQP120C

traces to: RQP120D

traces to: RQP120E

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

Traceability:: traces to: RQP120A

Traceability:: traces to: RQP120E

Traceability:: traces to: RQP120C

Traceability:: traces to: RQP120B

Traceability:: traces to: RQP120I

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

Definition at line 192 of file qep_hsm.cpp.

◆ isIn()

bool isIn ( QStateHandler const s )

noexcept

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

Traceability:

traces to: RQP103

traces to: RQP120S

Precondition: state configuration must be stable

Definition at line 486 of file qep_hsm.cpp.

◆ state()

QStateHandler state ( void ) const

inlinenoexcept

Note: used in the QM code generation

Definition at line 332 of file qep.hpp.

◆ childState()

QStateHandler childState ( QStateHandler const parent )

noexcept

Note: used in the QM code generation

Postcondition: the child must be confirmed

Definition at line 511 of file qep_hsm.cpp.

◆ top()

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

staticnoexcept

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 parameters to this state handler are not used. They are provided for conformance with the state-handler function signature QP::QStateHandler.

Traceability:

traces to: RQP103

traces to: RQP120T

Definition at line 185 of file qep_hsm.cpp.

◆ tran()

QState tran ( QStateHandler const target )

inlineprotectednoexcept

Definition at line 419 of file qep.hpp.

◆ tran_hist()

QState tran_hist ( QStateHandler const hist )

inlineprotectednoexcept

Definition at line 425 of file qep.hpp.

◆ super()

QState super ( QStateHandler const superstate )

inlineprotectednoexcept

Definition at line 431 of file qep.hpp.

◆ qm_tran()

QState qm_tran ( void const *const tatbl )

inlineprotectednoexcept

Definition at line 445 of file qep.hpp.

◆ qm_tran_hist()

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

inlineprotectednoexcept

Definition at line 452 of file qep.hpp.

◆ qm_tran_init()

QState qm_tran_init ( void const *const tatbl )

inlineprotectednoexcept

Definition at line 462 of file qep.hpp.

◆ qm_tran_ep()

QState qm_tran_ep ( void const *const tatbl )

inlineprotectednoexcept

Definition at line 469 of file qep.hpp.

◆ qm_tran_xp()

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

inlineprotectednoexcept

Definition at line 476 of file qep.hpp.

◆ qm_entry()

QState qm_entry ( QMState const *const s )

inlineprotectednoexcept

Definition at line 486 of file qep.hpp.

◆ qm_exit()

QState qm_exit ( QMState const *const s )

inlineprotectednoexcept

Definition at line 492 of file qep.hpp.

◆ getStateHandler()

QStateHandler getStateHandler ( )

protectedvirtualnoexcept

Reimplemented in QMsm, and QMActive.

Definition at line 480 of file qep_hsm.cpp.

◆ qm_sm_exit()

QState qm_sm_exit ( QMState const *const s )

inlineprotectednoexcept

Definition at line 514 of file qep.hpp.

◆ qm_super_sub()

QState qm_super_sub ( QMState const *const s )

inlineprotectednoexcept

Definition at line 521 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

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.

Traceability:

traces to: RQP103

traces to: RQP120E

traces to: RQP120F

Definition at line 348 of file qep_hsm.cpp.

Friends And Related Function Documentation

◆ QMsm

friend class QMsm

friend

Definition at line 548 of file qep.hpp.

◆ QActive

friend class QActive

friend

Definition at line 549 of file qep.hpp.

◆ QMActive

friend class QMActive

friend

Definition at line 550 of file qep.hpp.

◆ QF

friend class QF

friend

Definition at line 551 of file qep.hpp.

◆ QS

friend class QS

friend

Definition at line 552 of file qep.hpp.

◆ QXK

friend class QXK

friend

Definition at line 553 of file qep.hpp.

◆ QXThread

friend class QXThread

friend

Definition at line 554 of file qep.hpp.

◆ QXMutex

friend class QXMutex

friend

Definition at line 555 of file qep.hpp.

◆ QXSemaphore

friend class QXSemaphore

friend

Definition at line 556 of file qep.hpp.

◆ QHsmDummy

friend class QHsmDummy ( void )

friend

Definition at line 558 of file qep.hpp.

◆ QActiveDummy

friend class QActiveDummy

friend

Definition at line 559 of file qep.hpp.

Member Data Documentation

◆ m_state

QHsmAttr m_state

private

Definition at line 259 of file qep.hpp.

◆ m_temp

QHsmAttr m_temp

private

Definition at line 260 of file qep.hpp.

◆ Q_RET_SUPER

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

staticconstexpr

Definition at line 379 of file qep.hpp.

◆ Q_RET_SUPER_SUB

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

staticconstexpr

Definition at line 382 of file qep.hpp.

◆ Q_RET_UNHANDLED

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

staticconstexpr

Definition at line 385 of file qep.hpp.

◆ Q_RET_HANDLED

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

staticconstexpr

Definition at line 388 of file qep.hpp.

◆ Q_RET_IGNORED

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

staticconstexpr

Definition at line 391 of file qep.hpp.

◆ Q_RET_ENTRY

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

staticconstexpr

Definition at line 394 of file qep.hpp.

◆ Q_RET_EXIT

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

staticconstexpr

Definition at line 397 of file qep.hpp.

◆ Q_RET_NULL

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

staticconstexpr

Definition at line 400 of file qep.hpp.

◆ Q_RET_TRAN

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

staticconstexpr

Definition at line 403 of file qep.hpp.

◆ Q_RET_TRAN_INIT

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

staticconstexpr

Definition at line 406 of file qep.hpp.

◆ Q_RET_TRAN_EP

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

staticconstexpr

Definition at line 409 of file qep.hpp.

◆ Q_RET_TRAN_HIST

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

staticconstexpr

Definition at line 412 of file qep.hpp.

◆ Q_RET_TRAN_XP

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

staticconstexpr

Definition at line 415 of file qep.hpp.

◆ MAX_NEST_DEPTH_

constexpr std::int_fast8_t MAX_NEST_DEPTH_ {6}

staticconstexprprivate

Definition at line 528 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()

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

◆ QHsmDummy

◆ QActiveDummy

Member Data 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_