QP/C  7.0.0
Real-Time Embedded Framework
QActive Struct Reference

#include <qf.h>

Inheritance diagram for QActive:
QHsm QActiveDummy QMActive QTicker QXThread

Protected Member Functions

void QActive_ctor (QActive *const me, QStateHandler initial)
 
void QActive_stop (QActive *const me)
 
void QActive_subscribe (QActive const *const me, enum_t const sig)
 
void QActive_unsubscribe (QActive const *const me, enum_t const sig)
 
void QActive_unsubscribeAll (QActive const *const me)
 
bool QActive_defer (QActive const *const me, QEQueue *const eq, QEvt const *const e)
 
bool QActive_recall (QActive *const me, QEQueue *const eq)
 
uint_fast16_t QActive_flushDeferred (QActive const *const me, QEQueue *const eq)
 
void QActive_setAttr (QActive *const me, uint32_t attr1, void const *attr2)
 
- Protected Member Functions inherited from QHsm
void QHsm_ctor (QHsm *const me, QStateHandler initial)
 
QState QHsm_top (void const *const me, QEvt const *const e)
 

Protected Attributes

QHsm super
 

Private Member Functions

bool QActive_post_ (QActive *const me, QEvt const *const e, uint_fast16_t const margin, void const *const sender)
 
void QActive_postLIFO_ (QActive *const me, QEvt const *const e)
 
QEvt const * QActive_get_ (QActive *const me)
 
void QActive_start_ (QActive *const me, uint_fast8_t prio, QEvt const **const qSto, uint_fast16_t const qLen, void *const stkSto, uint_fast16_t const stkSize, void const *const par)
 

Private Attributes

uint8_t prio
 

Additional Inherited Members

- Public Member Functions inherited from QHsm
QStateHandler QHsm_childState (QHsm *const me, QStateHandler const parent)
 
bool QHsm_isIn (QHsm *const me, QStateHandler const state)
 
- Static Public Member Functions inherited from QHsm
static QStateHandler QHsm_state (QHsm *const me)
 

Detailed Description

Active Object base class (based on QHsm implementation)

Active objects in QP are encapsulated state machines (each embedding an event queue and a thread) 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.

QActive represents an active object that uses the QHsm-style implementation strategy for state machines. This strategy is tailored to manual coding, but it is also supported by the QM modeling tool. The resulting code is slower than in the QMsm style implementation strategy.

Traceability:
traces to: AQP212
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 (see oop).
typedef struct {
QActive super; /* inherits QActive */
QTimeEvt timeEvt; /* to timeout the blinking */
} Blinky;
. . .
void Blinky_ctor(Blinky * const me) {
/* constructor of the superclass <--- */
QActive_ctor(&me->super, Q_STATE_CAST(&Blinky_initial));
/* constructor(s) of the members */
QTimeEvt_ctorX(&me->timeEvt, &me->super, TIMEOUT_SIG, 0U);
}
#define Q_STATE_CAST(handler_)
Definition: qep.h:196
Definition: qf.h:107
void QActive_ctor(QActive *const me, QStateHandler initial)
Definition: qf_qact.c:58
QHsm super
Definition: qf.h:108
Definition: qf.h:456

Definition at line 107 of file qf.h.

Member Function Documentation

◆ QActive_ctor()

void QActive_ctor ( QActive *const  me,
QStateHandler  initial 
)
protected

protected "constructor" of an QActive active object

Performs the first step of active object initialization by assigning the virtual pointer and calling the superclass constructor.

Parameters
[in,out]mepointer (see oop)
[in]initialpointer to the event to be dispatched to the MSM
Note
Must be called only once before QMSM_INIT().
See also
QMsm_ctor() and QHsm_ctor()

Definition at line 58 of file qf_qact.c.

◆ QActive_stop()

void QActive_stop ( QActive *const  me)
protected

Stops execution of an active object and removes it from the framework's supervision.

Attention
QActive_stop() must be called only from the AO that is about to stop its execution. By that time, any pointers or references to the AO are considered invalid (dangling) and it becomes illegal for the rest of the application to post events to the AO.

Definition at line 215 of file qutest.c.

◆ QActive_subscribe()

void QActive_subscribe ( QActive const *const  me,
enum_t const  sig 
)
protected

Subscribes for delivery of signal sig to the active object me.

This function is part of the Publish-Subscribe event delivery mechanism available in QF. Subscribing to an event means that the framework will start posting all published events with a given signal sig to the event queue of the active object me.

Parameters
[in,out]mepointer (see oop)
[in]sigevent signal to subscribe
Usage
The following example shows how the Table active object subscribes to three signals in the initial transition:
QState Table_initial(Table * const me, QEvt const * const e) {
(void)e; /* unused parameter */
/* subscribe to event signals... */
QActive_subscribe(&me->super, (enum_t)HUNGRY_SIG);
QActive_subscribe(&me->super, (enum_t)DONE_SIG);
QActive_subscribe(&me->super, (enum_t)TERMINATE_SIG);
for (uint8_t n = 0U; n < N; ++n) {
me->fork[n] = FREE;
me->isHungry[n] = false;
}
return Q_TRAN(&Table_serving);
}
#define Q_TRAN(target_)
Definition: qep.h:526
uint_fast8_t QState
Definition: qep.h:170
signed int enum_t
Definition: qep.h:60
void QActive_subscribe(QActive const *const me, enum_t const sig)
Definition: qf_ps.c:204
Definition: qep.h:119
See also
QF_publish_(), QActive_unsubscribe(), and QActive_unsubscribeAll()

Definition at line 204 of file qf_ps.c.

◆ QActive_unsubscribe()

void QActive_unsubscribe ( QActive const *const  me,
enum_t const  sig 
)
protected

Un-subscribes from the delivery of signal sig to the AO me.

This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from an event means that the framework will stop posting published events with a given signal sig to the event queue of the active object me.

Parameters
[in]mepointer (see oop)
[in]sigevent signal to unsubscribe
Note
Due to the latency of event queues, an active object should NOT assume that a given signal sig will never be dispatched to the state machine of the active object after un-subscribing from that signal. The event might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events.
Un-subscribing from a signal that has never been subscribed in the first place is considered an error and QF will raise an assertion.
See also
QF_publish_(), QActive_subscribe(), and QActive_unsubscribeAll()
Precondition
the singal and the prioriy must be in ragne, the AO must also be registered with the framework

Definition at line 253 of file qf_ps.c.

◆ QActive_unsubscribeAll()

void QActive_unsubscribeAll ( QActive const *const  me)
protected

Un-subscribes from the delivery of all signals to the AO me.

This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from all events means that the framework will stop posting any published events to the event queue of the active object me.

Parameters
[in]mepointer (see oop)
Note
Due to the latency of event queues, an active object should NOT assume that no events will ever be dispatched to the state machine of the active object after un-subscribing from all events. The events might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events. Also, the alternative event-delivery mechanisms, such as direct event posting or time events, can be still delivered to the event queue of the active object.
See also
QF_publish_(), QActive_subscribe(), and QActive_unsubscribe()

Definition at line 303 of file qf_ps.c.

◆ QActive_defer()

bool QActive_defer ( QActive const *const  me,
QEQueue *const  eq,
QEvt const *const  e 
)
protected

Defer an event e to a given event queue eq.

This function is part of the event deferral support. An active object uses this function to defer an event e to the QF-supported native event queue eq. QF correctly accounts for another outstanding reference to the event and will not recycle the event at the end of the RTC step. Later, the active object might recall one event at a time from the event queue.

Parameters
[in,out]mepointer (see oop)
[in]eqpointer to a "raw" thread-safe queue to recall an event from.
[in]epointer to the event to be deferred
Returns
'true' (success) when the event could be deferred and 'false' (failure) if event deferral failed due to overflowing the queue.

An active object can use multiple event queues to defer events of different kinds.

See also
QActive_recall(), QEQueue, QActive_flushDeferred()

Definition at line 71 of file qf_defer.c.

◆ QActive_recall()

bool QActive_recall ( QActive *const  me,
QEQueue *const  eq 
)
protected

Recall a deferred event from a given event queue eq.

This function is part of the event deferral support. An active object uses this function to recall a deferred event from a given QF event queue. Recalling an event means that it is removed from the deferred event queue eq and posted (LIFO) to the event queue of the active object.

Parameters
[in,out]mepointer (see oop)
[in]eqpointer to a "raw" thread-safe queue to recall an event from.
Returns
'true' if an event has been recalled and 'false' if not.
Note
An active object can use multiple event queues to defer events of different kinds.
See also
QActive_recall(), QEQueue, QACTIVE_POST_LIFO()

Definition at line 111 of file qf_defer.c.

◆ QActive_flushDeferred()

uint_fast16_t QActive_flushDeferred ( QActive const *const  me,
QEQueue *const  eq 
)
protected

Flush the specified deferred queue eq.

This function is part of the event deferral support. An active object can use this function to flush a given QF event queue. The function makes sure that the events are not leaked.

Parameters
[in,out]mepointer (see oop)
[in]eqpointer to a "raw" thread-safe queue to flush.
Returns
the number of events actually flushed from the queue.
See also
QActive_defer(), QActive_recall(), QEQueue

Definition at line 181 of file qf_defer.c.

◆ QActive_setAttr()

void QActive_setAttr ( QActive *const  me,
uint32_t  attr1,
void const *  attr2 
)
protected

Generic setting of additional attributes (useful in QP ports)

◆ QActive_post_()

bool QActive_post_ ( QActive *const  me,
QEvt const *const  e,
uint_fast16_t const  margin,
void const *const  sender 
)
private

Direct event posting is the simplest asynchronous communication method available in QF.

Parameters
[in,out]mepointer (see oop)
[in]epointer to the event to be posted
[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]senderpointer to a sender object (used only for QS tracing)
Returns
'true' (success) if the posting succeeded (with the provided margin) and 'false' (failure) when the posting fails.
Note
The QF_NO_MARGIN value of the margin parameter is special and denotes situation when the post() operation is assumed to succeed (event delivery guarantee). An assertion fires, when the event cannot be delivered in this case.
Attention
This function should be called only via the macro QACTIVE_POST() or QACTIVE_POST_X().
Usage
extern QActive * const AO_Table;
QState Philoso_hungry(Philo * const me, QEvt const * const e) {
QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
TableEvt *pe = Q_NEW(TableEvt, HUNGRY_SIG); /* dynamic alloc */
pe->philNum = me->num;
QACTIVE_POST(AO_Table, &pe->super, me); /* <--- */
status = Q_HANDLED();
break;
}
. . .
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}
#define Q_HANDLED()
Definition: qep.h:554
#define Q_SUPER(super_)
Definition: qep.h:548
@ Q_ENTRY_SIG
Definition: qep.h:688
#define QACTIVE_POST(me_, e_, sender_)
Definition: qf.h:238
#define Q_NEW(evtT_, sig_)
Definition: qf.h:773
QSignal sig
Definition: qep.h:123
QState QHsm_top(void const *const me, QEvt const *const e)
Definition: qep_hsm.c:261
See also
QActive_post_(), QActive_postLIFO()

Prototype of the internal active object post (FIFO) implementation.

Precondition
event pointer must be valid

Definition at line 83 of file qf_actq.c.

◆ QActive_postLIFO_()

void QActive_postLIFO_ ( QActive *const  me,
QEvt const *const  e 
)
private

posts an event to the event queue of the active object me using the Last-In-First-Out (LIFO) policy.

Note
The LIFO policy should be used only for self-posting and with caution, because it alters order of events in the queue.
Parameters
[in]mepointer (see oop)
[in]epointer to the event to post to the queue
Attention
This function should be called only via the macro QACTIVE_POST_LIFO().
See also
QActive_post_(), QACTIVE_POST(), QACTIVE_POST_X()

Prototype of the internal active object post LIFO implementation.

Definition at line 221 of file qf_actq.c.

◆ QActive_get_()

QEvt const * QActive_get_ ( QActive *const  me)
private

The behavior of this function depends on the kernel/OS used in the QF port. For built-in kernels (QV or QK) the function can be called only when the queue is not empty, so it doesn't block. For a blocking kernel/OS the function can block and wait for delivery of an event.

Parameters
[in,out]mepointer (see oop)
Returns
a pointer to the received event. The returned pointer is guaranteed to be valid (can't be NULL).
Note
This function is used internally by a QF port to extract events from the event queue of an active object. This function depends on the event queue implementation and is sometimes customized in the QF port (file qf_port.h). Depending on the definition of the macro QACTIVE_EQUEUE_WAIT_(), the function might block the calling thread when no events are available.

Get an event from the event queue of an active object.

Definition at line 310 of file qf_actq.c.

◆ QActive_start_()

void QActive_start_ ( QActive *const  me,
uint_fast8_t  prio,
QEvt const **const  qSto,
uint_fast16_t const  qLen,
void *const  stkSto,
uint_fast16_t const  stkSize,
void const *const  par 
)
private

Definition at line 87 of file qutest.c.

Field Documentation

◆ super

QHsm super
protected

inherits QHsm

Definition at line 108 of file qf.h.

◆ prio

uint8_t prio
private

QF priority (1..QF_MAX_ACTIVE) of this active object.

Definition at line 152 of file qf.h.


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