QP-nano  6.9.0
Real-Time Embedded Framework
QHsm Struct Reference

#include <qepn.h>

Inheritance diagram for QHsm:
QActive

Public Member Functions

#define QHsm_childState(me_, parent_)    QHsm_childState_(Q_HSM_UPCAST(me_), Q_STATE_CAST(parent_))
 

Data Fields

QHsmVtable const * vptr
 
QStateHandler state
 
QStateHandler temp
 
QEvt evt
 

Protected Member Functions

void QHsm_ctor (QHsm *const me, QStateHandler initial)
 
QState QHsm_top (void const *const me)
 

Private Member Functions

void QHsm_init_ (QHsm *const me)
 
void QHsm_dispatch_ (QHsm *const me)
 
QStateHandler QHsm_childState_ (QHsm *const me, QStateHandler const parent)
 

Static Private Member Functions

static int_fast8_t QHsm_tran_ (QHsm *const me, QStateHandler path[QHSM_MAX_NEST_DEPTH_])
 

Detailed Description

Hierarchical State Machine

Description
QHsm represents a Hierarchical Finite State Machine (HSM) with full support for hierarchical nesting of states, entry/exit actions, and initial transitions in any composite state.
Note
QHsm is not intended to be instantiated directly, but rather serves as the base structure for derivation of state machines in the application code.
Usage
The following example illustrates how to derive a state machine structure from QHsm. Please note that the QHsm member 'super' is defined as the first member of the derived struct.
typedef struct {
QHsm super; /* inherits QHsm */
double operand1;
double operand2;
char display[DISP_WIDTH + 1];
uint8_t len;
uint8_t opKey;
} Calc;
Definition: qepn.h:183
See also
Object Orientation

Definition at line 183 of file qepn.h.

Member Function Documentation

◆ QHsm_ctor()

void QHsm_ctor ( QHsm *const  me,
QStateHandler  initial 
)
protected

"constructor" of a HSM.

Description
Performs the first step of HSM initialization by assigning the initial pseudostate to the currently active state of the state machine.
Parameters
[in,out]mepointer (see Object Orientation)
[in]initialpointer to the top-most initial state-handler function in the derived state machine
Note
Must be called only by the constructors of the derived state machines.
Must be called only ONCE before QHSM_INIT().
Usage
The following example illustrates how to invoke QHsm_ctor() in the "constructor" of a derived state machine:
void Alarm_ctor(Alarm * const me) {
QHsm_ctor(&me->super, Q_STATE_CAST(&Alarm_initial));
}
#define Q_STATE_CAST(handler_)
Definition: qepn.h:340
void QHsm_ctor(QHsm *const me, QStateHandler initial)
Definition: qepn.c:84

Definition at line 84 of file qepn.c.

◆ QHsm_init_()

void QHsm_init_ ( QHsm *const  me)
private

Implementation of the top-most initial transition in QHsm.

Description
Executes the top-most initial transition in a HSM.
Parameters
[in,out]mepointer (see Object Orientation)
Note
Must be called only ONCE after the QHsm_ctor().
Precondition
the virtual pointer must be initialized, the top-most initial transition must be initialized, and the initial transition must not be taken yet.

Definition at line 105 of file qepn.c.

◆ QHsm_dispatch_()

void QHsm_dispatch_ ( QHsm *const  me)
private

Implementation of dispatching events 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,out]mepointer (see Object Orientation)
Note
This function should be called only via the virtual table (see QHSM_DISPATCH()) and should NOT be called directly in the applications.
Precondition
the current state must be initialized and the state configuration must be stable

Definition at line 190 of file qepn.c.

◆ QHsm_top()

QState QHsm_top ( void const *const  me)
protected

the top-state.

Description
QHsm_top() is the ultimate root of state hierarchy in all HSMs derived from QHsm.
Parameters
[in]mepointer (see Object Orientation)
Returns
Always returns Q_RET_IGNORED, which means that the top state ignores all events.
Note
The parameter me to this state handler is not used. It is provided for conformance with the state-handler function signature QStateHandler.

Definition at line 172 of file qepn.c.

◆ QHsm_tran_()

static int_fast8_t QHsm_tran_ ( QHsm *const  me,
QStateHandler  path[QHSM_MAX_NEST_DEPTH_] 
)
staticprivate
Description
Static helper function to execute transition sequence in a hierarchical state machine (HSM).
Parameters
[in,out]mepointer (see Object Orientation)
[in,out]patharray of pointers to state-handler functions to execute the entry actions
Returns
the depth of the entry path stored in the path parameter.

Definition at line 292 of file qepn.c.

◆ QHsm_childState_()

QStateHandler QHsm_childState_ ( QHsm *const  me,
QStateHandler const  parent 
)
private
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]mepointer (see Object Orientation)
[in]parentpointer to the state-handler function
Returns
the child of a given parent state, which is an ancestor of the current active state. For the corner case when the currently active state is the given parent state, function returns the parent 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.
See also
QHsm_childState()
Postcondition
the child must be found

Definition at line 450 of file qepn.c.

Field Documentation

◆ vptr

QHsmVtable const* vptr

virtual pointer

Definition at line 184 of file qepn.h.

◆ state

current active state (state-variable)

Definition at line 185 of file qepn.h.

◆ temp

temporary: tran. chain, target state, etc.

Definition at line 186 of file qepn.h.

◆ evt

QEvt evt

currently processed event in the HSM (protected)

Definition at line 187 of file qepn.h.


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