Active object class (based on the QHsm implementation strategy) More...
#include "qf.h"
Public Member Functions | |
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) |
void | QActive_setAttr (QActive *const me, uint32_t attr1, void const *attr2) |
![]() | |
bool | QHsm_isIn (QHsm *const me, QStateHandler const state) |
QStateHandler | QHsm_childState (QHsm *const me, QStateHandler const parent) |
Static Public Member Functions | |
void | QActive_psInit (QSubscrList *const subscrSto, enum_t const maxSignal) |
![]() | |
static QStateHandler | QHsm_state (QHsm *const me) |
Public Attributes | |
QHsm | super |
Protected Member Functions | |
void | QActive_ctor (QActive *const me, QStateHandler const initial) |
void | QActive_stop (QActive *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_register_ (QActive *const me) |
void | QActive_unregister_ (QActive *const me) |
![]() | |
void | QHsm_ctor (QHsm *const me, QStateHandler const initial) |
QState | QHsm_top (QHsm const *const me, QEvt const *const e) |
void | QHsm_init_ (QHsm *const me, void const *const e, uint_fast8_t const qs_id) |
void | QHsm_dispatch_ (QHsm *const me, QEvt const *const e, uint_fast8_t const qs_id) |
Private Member Functions | |
void | QActive_start_ (QActive *const me, QPrioSpec const prioSpec, QEvt const **const qSto, uint_fast16_t const qLen, void *const stkSto, uint_fast16_t const stkSize, void const *const par) |
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) |
Static Private Member Functions | |
void | QActive_publish_ (QEvt const *const e, void const *const sender, uint_fast8_t const qs_id) |
void | QActive_thread_ (QActive *act) |
Private Attributes | |
QF_EQUEUE_TYPE | eQueue |
QF_OS_OBJECT_TYPE | osObject |
QF_THREAD_TYPE | thread |
uint8_t | prio |
uint8_t | pthre |
QActive * | QActive_active_ [QF_MAX_ACTIVE+1U] |
QSubscrList * | QActive_subscrList_ |
enum_t | QActive_maxPubSignal_ |
QActive * | QActive_registry_ [QF_MAX_ACTIVE+1U] |
Active objects are encapsulated tasks (each containing an event queue and a state machine) that communicate with one another asynchronously by sending and receiving events. Within an active object, events are processed 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.
|
protected |
QActive constructor (abstract base class)
[in,out] | me | current instance pointer (see oop) |
[in] | initial | pointer to the top-most initial state-handler function in the derived active object |
|
private |
Starts execution of an active object and registers the object with the framework
Starts execution of the AO and registers the AO with the framework.
[in,out] | me | current instance pointer (see oop) |
[in] | prioSpec | priority specification for the AO (See QPrioSpec) |
[in] | qSto | pointer to the storage for the ring buffer of the event queue |
[in] | qLen | length of the event queue [# QEvt* pointers] |
[in] | stkSto | pointer to the stack storage (might be NULL) |
[in] | stkSize | stack size [bytes] |
[in] | par | pointer to an extra parameter (might be NULL) |
|
protected |
Stops execution of an active object and removes it from the framework's supervision
[in,out] | me | current instance pointer (see oop) |
|
private |
Posts an event e
directly to the event queue of the active object using the First-In-First-Out (FIFO) policy.
Direct event posting is the simplest asynchronous communication method available in QF.
[in,out] | me | current instance pointer (see oop) |
[in] | e | pointer to the event to be posted |
[in] | margin | number of required free slots in the queue after posting the event or QF_NO_MARGIN. |
[in] | sender | pointer to a sender object (used in QS only) |
qf_actq:100
qf_actq:190
margin
== QF_NO_MARGIN)margin
== QF_NO_MARGIN, this function will assert internally if the event posting fails. In that case, it is unnecessary to check the retrun value from this function.Posts an event e
directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy.
The LIFO policy should be used only for self-posting and with caution, because it alters order of events in the queue.
[in,out] | me | current instance pointer (see oop) |
[in] | e | pointer to the event to be posted |
qf_actq:200
Get an event from the event queue of an active object
The behavior of this function depends on the kernel used in the QF port. For built-in kernels (Vanilla 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.
[in,out] | me | current instance pointer (see oop) |
Subscribes for delivery of signal sig
to the active object
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.
[in,out] | me | current instance pointer (see oop) |
[in] | sig | event signal to subscribe |
qf_ps:300
The following example shows how the Table active object subscribes to three signals in the initial transition:
Unsubscribes from the delivery of signal sig
to the active object
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.
[in,out] | me | current instance pointer (see oop) |
[in] | sig | event signal to unsubscribe |
qf_ps:400
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.void QActive_unsubscribeAll | ( | QActive const *const | me | ) |
Unsubscribes from the delivery of all signals to the active object
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.
[in,out] | me | current instance pointer (see oop) |
qf_ps:500
|
static |
Publish event to all subscribers of a given signal e->sig
This function posts (using the FIFO policy) the event e to all active objects that have subscribed to the signal e->sig, which is called multicasting. The multicasting performed in this function is very efficient based on reference-counting inside the published event ("zero-copy" event multicasting). This function is designed to be callable from any part of the system, including ISRs, device drivers, and active objects.
|
staticprivate |
Publish event to all subscribers of a given signal e->sig
This function posts (using the FIFO policy) the event e to all active objects that have subscribed to the signal e->sig, which is called multicasting. The multicasting performed in this function is very efficient based on reference-counting inside the published event ("zero-copy" event multicasting). This function is designed to be callable from any part of the system, including ISRs, device drivers, and active objects.
qf_ps:200
Defer an event to a given separate event queue
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.
[in] | eq | pointer to a "raw" thread-safe queue to recall an event from. |
[in] | e | pointer to the event to be deferred |
An active object can use multiple event queues to defer events of different kinds.
Recall a deferred event from a given event queue
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.
[in] | eq | pointer to a "raw" thread-safe queue to recall an event from. |
Definition at line 88 of file qf_defer.c.
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.
[in] | eq | pointer to a "raw" thread-safe queue to flush. |
Definition at line 147 of file qf_defer.c.
void QActive_setAttr | ( | QActive *const | me, |
uint32_t | attr1, | ||
void const * | attr2 | ||
) |
Generic setting of additional attributes (useful in QP ports)
|
staticprivate |
Thread routine for executing an active object act
|
protected |
Register this active object to be managed by the framework
This function adds a given active object to the active objects managed by the QF framework. It should not be called by the application directly, only through the function QActive::start().
[in,out] | me | current instance pointer (see oop) |
qf_qact:100
qf_qact:190
|
protected |
Un-register the active object from the framework
This function un-registers a given active object from the active objects managed by the QF framework. It should not be called by the QP ports.
[in] | me | pointer to the active object to remove from the framework. |
qf_qact:200
|
private |
OS-dependent event-queue type
The type of the queue depends on the underlying operating system or a kernel. Many kernels support "message queues" that can be adapted to deliver QF events to the active object. Alternatively, QF provides a native event queue implementation that can be used as well.
|
private |
|
private |
OS-dependent representation of the thread of the active object
This data might be used in various ways, depending on the QF port. In some ports me->thread is used store the thread handle. In other ports me->thread can be a pointer to the Thread-Local-Storage (TLS).
|
private |
|
private |
preemption-threshold [1..QF_MAX_ACTIVE] of this AO.
|
private |
|
private |
|
private |
|
private |