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

#include <qfn.h>

Inheritance diagram for QActive:
QHsm

Public Member Functions

void QActive_armX (QActive *const me, uint_fast8_t const tickRate, QTimeEvtCtr const nTicks, QTimeEvtCtr const interval)
 
void QActive_disarmX (QActive *const me, uint_fast8_t const tickRate)
 
- Public Member Functions inherited from QHsm
#define QHsm_childState(me_, parent_)    QHsm_childState_(Q_HSM_UPCAST(me_), Q_STATE_CAST(parent_))
 

Data Fields

QHsm super
 derives from the QHsm base class More...
 
QTimer tickCtr [QF_MAX_TICK_RATE]
 
uint8_t prio
 
uint8_t volatile head
 
uint8_t volatile tail
 
uint8_t volatile nUsed
 
- Data Fields inherited from QHsm
QHsmVtable const * vptr
 
QStateHandler state
 
QStateHandler temp
 
QEvt evt
 

Protected Member Functions

void QActive_ctor (QActive *const me, QStateHandler initial)
 
- Protected Member Functions inherited from QHsm
void QHsm_ctor (QHsm *const me, QStateHandler initial)
 
QState QHsm_top (void const *const me)
 

Private Member Functions

bool QActive_postX_ (QActive *const me, uint_fast8_t margin, enum_t const sig, QParam const par)
 
bool QActive_postXISR_ (QActive *const me, uint_fast8_t margin, enum_t const sig, QParam const par)
 

Detailed Description

QActive active object (based on QHsm-implementation)

Description
QActive is the base structure for derivation of active objects. Active objects in QF-nano are encapsulated tasks (each embedding a state machine and an event queue) that communicate with one another asynchronously by sending and receiving events. Within an active object, events are processed sequentially in a run-to-completion (RTC) fashion, while QF encapsulates all the details of thread-safe event exchange and queuing.
Note
QActive is not intended to be instantiated directly, but rather serves as the base structure for derivation of active objects in the application code.
Usage
The following example illustrates how to derive an active object from QActive. Please note that the QActive member super_ is defined as the first member of the derived struct.
/* PEdestrian Light CONtrolled (PELICAN) crossing active object */
typedef struct {
QActive super; /* inherits QActive */
uint8_t pedFlashCtr; /* pedestrian flash counter */
} Pelican;
/* the ctor */
void Pelican_ctor(Pelican * const me, uint8_t timeout) {
/* call the superclass' ctor... */
QActive_ctor(&me->super, Q_STATE_CAST(&Pelican_initial));
. . . /* initialize the added attributes */
}
#define Q_STATE_CAST(handler_)
Definition: qepn.h:340
Definition: qfn.h:122
void QActive_ctor(QActive *const me, QStateHandler initial)
Definition: qfn.c:99
QHsm super
derives from the QHsm base class
Definition: qfn.h:123

Definition at line 122 of file qfn.h.

Member Function Documentation

◆ QActive_postX_()

bool QActive_postX_ ( QActive *const  me,
uint_fast8_t  margin,
enum_t const  sig,
QParam const  par 
)
private

Implementation of the task-level event posting

Description
Direct event posting is the simplest asynchronous communication method available in QF-nano.
Attention
This function should be called only via the macro QACTIVE_POST() or QACTIVE_POST_X(). This function should be only used in the task context.
Parameters
[in,out]mepointer (see Object Orientation)
[in]marginnumber of required free slots in the queue after posting the event. The special value QF_NO_MARGIN means that this function will assert if posting fails.
[in]sigsignal of the event to be posted
[in]parparameter of the event to be posted
Usage
/* "extended" event posting from the interrupt context (QACTIVE_POST_X_ISR) */
void SysTick_Handler(void) {
. . .
if (!QACTIVE_POST_X_ISR((QActive *)&AO_Cruncher,
5U, /* margin of free slots in the queue */
ECHO_SIG, 0U)) /* signal and parameter */
{
/* event posting failed... */
}
}
/* "extended" event posting from the task context (QACTIVE_POST_X())... */
static QState Ship_flying(Ship * const me) {
QState status_;
switch (Q_SIG(me)) {
case TIME_TICK_SIG: {
. . .
if ((me->score % 10) == 0) { /* is the score "round"? */
if (!QACTIVE_POST_X((QActive *)&AO_Tunnel,
4U, /* margin of free slots in the queue */
SCORE_SIG, me->score)) /* signal and parameter */
{
/* event posting failed... */
}
}
status_ = Q_HANDLED();
break;
}
. . .
}
return status_;
}
#define Q_HANDLED()
Definition: qepn.h:370
#define Q_SIG(me_)
Definition: qepn.h:143
uint_fast8_t QState
Definition: qepn.h:155
#define QACTIVE_POST_X(me_, margin_, sig_, par_)
Definition: qfn.h:230
#define QACTIVE_POST_X_ISR(me_, margin_, sig_, par_)
Definition: qfn.h:279

Definition at line 143 of file qfn.c.

◆ QActive_postXISR_()

bool QActive_postXISR_ ( QActive *const  me,
uint_fast8_t  margin,
enum_t const  sig,
QParam const  par 
)
private

Implementation of the ISR-level event posting

Description
Direct event posting is the simplest asynchronous communication method available in QF-nano.
Attention
This function should be called only via the macro QACTIVE_POST_ISR() or QACTIVE_POST_X_ISR(). This function should be only used in the ISR context.
Parameters
[in,out]mepointer (see Object Orientation)
[in]marginnumber of required free slots in the queue after posting the event. The special value QF_NO_MARGIN means that this function will assert if posting fails.
[in]sigsignal of the event to be posted
[in]parparameter of the event to be posted
Usage
/* "extended" event posting from the interrupt context (QACTIVE_POST_X_ISR) */
void SysTick_Handler(void) {
. . .
if (!QACTIVE_POST_X_ISR((QActive *)&AO_Cruncher,
5U, /* margin of free slots in the queue */
ECHO_SIG, 0U)) /* signal and parameter */
{
/* event posting failed... */
}
}
/* "extended" event posting from the task context (QACTIVE_POST_X())... */
static QState Ship_flying(Ship * const me) {
QState status_;
switch (Q_SIG(me)) {
case TIME_TICK_SIG: {
. . .
if ((me->score % 10) == 0) { /* is the score "round"? */
if (!QACTIVE_POST_X((QActive *)&AO_Tunnel,
4U, /* margin of free slots in the queue */
SCORE_SIG, me->score)) /* signal and parameter */
{
/* event posting failed... */
}
}
status_ = Q_HANDLED();
break;
}
. . .
}
return status_;
}

Definition at line 229 of file qfn.c.

◆ QActive_armX()

void QActive_armX ( QActive *const  me,
uint_fast8_t const  tickRate,
QTimeEvtCtr const  nTicks,
QTimeEvtCtr const  interval 
)

Arm the QP-nano one-shot time event.

Description
Arms a time event to fire in a specified number of clock ticks at the specified tick rate. The timeout signal gets directly posted (using the FIFO policy) into the event queue of the active object calling this function.
Parameters
[in,out]mepointer (see Object Orientation)
[in]tickRatetick rate .
[in]nTicksnumber of clock ticks (at the associated rate) to rearm the time event with.
Note
Each system tick rate posts timeout events with a different signal as follows:
tickRate==0 Q_TIMEOUT_SIG
tickRate==1 Q_TIMEOUT1_SIG
tickRate==2 Q_TIMEOUT2_SIG
tickRate==3 Q_TIMEOUT3_SIG
After posting, a one-shot time event gets automatically disarmed.
A time event can be disarmed at any time by calling the QActive_disarmX() function.
Usage
The following example shows how to arm a time event from a state machine of an active object:
/* when #QF_TIMEEVT_PERIODIC is NOT defined... */
QState Pelican_carsGreen(Pelican * const me) {
QState status_;
switch (Q_SIG(me)) {
case Q_ENTRY_SIG: {
/* arm timer (one-shot) at tick rate 0 */
QActive_armX(&me->super, 0U,
CARS_GREEN_MIN_TOUT);
BSP_signalCars(CARS_GREEN);
status_ = Q_HANDLED();
break;
}
case Q_EXIT_SIG: {
QActive_disarm(&me->super)
status_ = Q_HANDLED();
break;
}
case Q_INIT_SIG: {
status_ = Q_TRAN(&Pelican_carsGreenNoPed);
break;
}
default: {
status_ = Q_SUPER(&Pelican_carsEnabled);
break;
}
}
return status_;
}
/* when #QF_TIMEEVT_PERIODIC is defined... */
QState Pelican_carsGreen(Pelican * const me) {
QState status_;
switch (Q_SIG(me)) {
case Q_ENTRY_SIG: {
/* arm timer (one-shot) at tick rate 0 */
QActive_armX(&me->super, 0U,
CARS_GREEN_MIN_TOUT, 0U);
BSP_signalCars(CARS_GREEN);
status_ = Q_HANDLED();
break;
}
case Q_EXIT_SIG: {
QActive_disarm(&me->super)
status_ = Q_HANDLED();
break;
}
case Q_INIT_SIG: {
status_ = Q_TRAN(&Pelican_carsGreenNoPed);
break;
}
default: {
status_ = Q_SUPER(&Pelican_carsEnabled);
break;
}
}
return status_;
}
#define Q_EXIT_SIG
Definition: qepn.h:385
#define Q_TRAN(target_)
Definition: qepn.h:346
#define Q_ENTRY_SIG
Definition: qepn.h:382
#define Q_INIT_SIG
Definition: qepn.h:388
#define Q_SUPER(super_)
Definition: qepn.h:364
void QActive_armX(QActive *const me, uint_fast8_t const tickRate, QTimeEvtCtr const nTicks, QTimeEvtCtr const interval)
Definition: qfn.c:462

Definition at line 462 of file qfn.c.

◆ QActive_disarmX()

void QActive_disarmX ( QActive *const  me,
uint_fast8_t const  tickRate 
)

Disarm a time event. Since the tick counter

Description
The time event of the active object gets disarmed (stopped).
Parameters
[in,out]mepointer (see Object Orientation)
[in]tickRatetick rate
Note
You should not assume that the timeout event will not arrive after you disarm the time event. The timeout event could be already in the event queue.

Definition at line 495 of file qfn.c.

◆ QActive_ctor()

void QActive_ctor ( QActive *const  me,
QStateHandler  initial 
)
protected
Note
QActive inherits QActive, so by the Object Orientation convention it should call the constructor of the superclass, i.e., QActive_ctor(). However, this would pull in the QActiveVtable, which in turn will pull in the code for QHsm_init_() and QHsm_dispatch_() implemetations, which is expensive. To avoid this code size penalty, in case QHsm is not used in a given project, the call to QHsm_ctor() avoids pulling in the code for QHsm.

Definition at line 99 of file qfn.c.

Field Documentation

◆ super

QHsm super

Definition at line 123 of file qfn.h.

◆ tickCtr

Timer for the active object

Definition at line 127 of file qfn.h.

◆ prio

uint8_t prio

priority of the active object (1..8)

Definition at line 131 of file qfn.h.

◆ head

uint8_t volatile head

offset to where next event will be inserted into the buffer

Definition at line 134 of file qfn.h.

◆ tail

uint8_t volatile tail

offset of where next event will be extracted from the buffer

Definition at line 137 of file qfn.h.

◆ nUsed

uint8_t volatile nUsed

number of events currently present in the queue (events in the ring buffer + 1 event in the state machine)

Definition at line 142 of file qfn.h.


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