Active object class (based on the QHsm implementation strategy). More...
#include <qp.h>
Public Member Functions | |
| void | QActive_setAttr (QActive *const me, uint32_t attr1, void const *attr2) |
| Generic setting of additional attributes (defined in some QP ports). | |
| void | QActive_start (QActive *const me, QPrioSpec const prioSpec, QEvtPtr *const qSto, uint_fast16_t const qLen, void *const stkSto, uint_fast16_t const stkSize, void const *const par) |
| Starts execution of an active object and registers the object with the framework. | |
Static Public Member Functions | |
| void | QActive_psInit (QSubscrList *const subscrSto, enum_t const maxSignal) |
| Publish event to all subscribers of a given signal e->sig. | |
| uint16_t | QActive_getQueueUse (uint_fast8_t const prio) |
| uint16_t | QActive_getQueueFree (uint_fast8_t const prio) |
| uint16_t | QActive_getQueueMin (uint_fast8_t const prio) |
| This function returns the minimum of free entries of the given event queue. | |
Protected Member Functions | |
| void | QActive_ctor (QActive *const me, QStateHandler const initial) |
| QActive constructor (abstract base class). | |
| void | QActive_stop (QActive *const me) |
| Stops execution of an active object and removes it from the framework's supervision. | |
| void | QActive_subscribe (QActive const *const me, enum_t const sig) |
| Subscribes for delivery of signal sig to the active object. | |
| void | QActive_unsubscribe (QActive const *const me, enum_t const sig) |
| Unsubscribes from the delivery of signal sig to the active object. | |
| void | QActive_unsubscribeAll (QActive const *const me) |
| Unsubscribes from the delivery of all signals to the active object. | |
| bool | QActive_defer (QActive const *const me, struct QEQueue *const eq, QEvt const *const e) |
| Defer an event to a given separate event queue. | |
| bool | QActive_recall (QActive *const me, struct QEQueue *const eq) |
| Recall a deferred event from a given event queue. | |
| uint16_t | QActive_flushDeferred (QActive const *const me, struct QEQueue *const eq, uint_fast16_t const num) |
| Flush the specified number of events from the deferred queue eq. | |
Protected Attributes | |
| QAsm | super |
| uint8_t | prio |
| QF-priority [1..QF_MAX_ACTIVE] of this AO. | |
| uint8_t | pthre |
| Preemption-threshold [1..QF_MAX_ACTIVE] of this AO. | |
| QACTIVE_THREAD_TYPE | thread |
| Port-dependent representation of the thread of the active object. | |
| QACTIVE_OS_OBJ_TYPE | osObject |
| Port-dependent per-thread object. | |
| QACTIVE_EQUEUE_TYPE | eQueue |
| Port-dependent event-queue type (often QEQueue). | |
| Protected Attributes inherited from QAsm | |
| struct QAsmVtable const * | vptr |
| Virtual pointer inherited by all QAsm subclasses (see also SAS_QP_OOA). | |
| union QAsmAttr | state |
| Current state (pointer to the current state-handler function). | |
| union QAsmAttr | temp |
| Temporary storage for target/act-table etc.. | |
Private Member Functions | |
| void | QActive_register_ (QActive *const me) |
| Register this active object to be managed by the framework. | |
| void | QActive_unregister_ (QActive *const me) |
| Un-register the active object from the framework. | |
| bool | QActive_post_ (QActive *const me, QEvt const *const e, uint_fast16_t const margin, void const *const sender) |
| Posts an event e directly to the event queue of the active object using the First-In-First-Out (FIFO) policy. | |
| void | QActive_postLIFO_ (QActive *const me, QEvt const *const e) |
| Posts an event e directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy. | |
| QEvt const * | QActive_get_ (QActive *const me) |
| Get an event from the event queue of an active object. | |
| void | QActive_evtLoop_ (QActive *const me) |
| Event loop thread routine for executing an active object act (defined some in QP ports). | |
Static Private Member Functions | |
| void | QActive_publish_ (QEvt const *const e, void const *const sender, uint_fast8_t const qsId) |
| Publish event to all subscribers of a given signal e->sig. | |
| static void | QActive_postFIFO_ (QActive *const me, QEvt const *const e, void const *const sender) |
| static void | QActive_multicast_ (QPSet *const subscrSet, QEvt const *const e, void const *const sender) |
Private Attributes | |
| QActive * | QActive_registry_ [QF_MAX_ACTIVE+1U] |
| Static (one per-class) array of registered active objects. | |
| QSubscrList * | QActive_subscrList_ |
| Static (one per-class) pointer to all subscriber AOs for a given event signal. | |
| QSignal | QActive_maxPubSignal_ |
| Static (one per-class) maximum published signal (the size of the subscrList_ array). | |
Active object class (based on the QHsm implementation strategy).
Details
Active Objects (a.k.a., Actors) are autonomous software objects, each possessing an event queue, execution context, and an internal state machine. All interactions with an Active Object occur by asynchronous posting of events, which are processed one at a time (to completion) in the execution context of the Active Object. As long as there is no sharing of data or resources among Active Objects (or any other concurrent entities), there are no concurrency hazards.
The QActive class 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.
Usage
The following example illustrates how to derive an active object from QActive.
Backward Traceability
Forward Traceability
|
protected |
QActive constructor (abstract base class).
| [in,out] | me | current instance pointer (see SAS_QP_OOA) |
| [in] | initial | pointer to the top-most initial state-handler function in the derived active object |
Forward Traceability
| void QActive_setAttr | ( | QActive *const | me, |
| uint32_t | attr1, | ||
| void const * | attr2 ) |
Generic setting of additional attributes (defined in some QP ports).
Forward Traceability
| void QActive_start | ( | QActive *const | me, |
| QPrioSpec const | prioSpec, | ||
| QEvtPtr *const | qSto, | ||
| uint_fast16_t const | qLen, | ||
| void *const | stkSto, | ||
| uint_fast16_t const | stkSize, | ||
| void const *const | par ) |
Starts execution of an active object and registers the object with the framework.
Details
Starts execution of the AO and registers the AO with the framework.
| [in,out] | me | current instance pointer (see SAS_QP_OOA) |
| [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 [# QEvtPtr 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) |
Usage
The following example shows starting an AO when a per-task stack is NOT needed:
Forward Traceability
|
protected |
Stops execution of an active object and removes it from the framework's supervision.
| [in,out] | me | current instance pointer (see SAS_QP_OOA) |
Forward Traceability
|
private |
Register this active object to be managed by the framework.
Details
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 SAS_QP_OOA) |
Forward Traceability
|
private |
Un-register the active object from the framework.
Details
This function unregisters a given active object from the active objects managed by the QF framework. The QP ports should not call it.
| [in] | me | pointer to the active object to remove from the framework. |
Forward Traceability
|
private |
Posts an event e directly to the event queue of the active object using the First-In-First-Out (FIFO) policy.
Details
Direct event posting is the simplest asynchronous communication method available in QF. Should be called only through the macro QACTIVE_POST().
| [in,out] | me | current instance pointer (see SAS_QP_OOA) |
| [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) |
Usage
Forward Traceability
Posts an event e directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy.
Details
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 SAS_QP_OOA) |
| [in] | e | pointer to the event to be posted |
Forward Traceability
Get an event from the event queue of an active object.
Details
This function is only for internal use inside the QP/C Framework and QP/C Application should not call this function (there is never a need for it). The behavior of this function depends on the kernel 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.
| [in,out] | me | current instance pointer (see SAS_QP_OOA) |
Forward Traceability
|
static |
Publish event to all subscribers of a given signal e->sig.
Details
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.
Backward Traceability
Forward Traceability
|
staticprivate |
Publish event to all subscribers of a given signal e->sig.
Details
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.
Usage
Forward Traceability
|
static |
|
static |
|
static |
This function returns the minimum of free entries of the given event queue.
Details
Queries the minimum of free ever present in the given event queue of an active object with priority prio, since the active object was started.
| [in] | prio | Priority of the active object, whose queue is queried |
Backward Traceability
Forward Traceability
Subscribes for delivery of signal sig to the active object.
Details
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 SAS_QP_OOA) |
| [in] | sig | event signal to subscribe |
Usage
The following example shows how the Table active object subscribes to three signals in the initial transition:
Forward Traceability
Unsubscribes from the delivery of signal sig to the active object.
Details
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Unsubscribing 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 SAS_QP_OOA) |
| [in] | sig | event signal to unsubscribe |
Forward Traceability
|
protected |
Unsubscribes from the delivery of all signals to the active object.
Details
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 SAS_QP_OOA) |
Forward Traceability
|
protected |
Defer an event to a given separate event queue.
Details
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,out] | me | current instance pointer (see SAS_QP_OOA) |
| [in] | eq | pointer to a "raw" thread-safe queue to recall an event from. |
| [in] | e | pointer to the event to be deferred |
Forward Traceability
Definition at line 44 of file qf_defer.c.
Recall a deferred event from a given event queue.
Details
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,out] | me | current instance pointer (see SAS_QP_OOA) |
| [in] | eq | pointer to a "raw" thread-safe queue to recall an event from. |
Forward Traceability
Definition at line 78 of file qf_defer.c.
|
protected |
Flush the specified number of events from the deferred queue eq.
Details
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,out] | me | current instance pointer (see SAS_QP_OOA) |
| [in] | eq | pointer to a "raw" thread-safe queue to flush. |
| [in] | num | number of events to flush (note can be a big number, like 0xFFFFU to flush all events) |
Forward Traceability
Definition at line 135 of file qf_defer.c.
|
private |
Event loop thread routine for executing an active object act (defined some in QP ports).
Forward Traceability
|
protected |
|
protected |
|
protected |
Port-dependent representation of the thread of the active object.
Details
This data might be used in various ways, depending on the QF port. In some ports, me->thread is used to store the thread handle. In other ports, me->thread can be a pointer to the Thread-Local-Storage (TLS).
Forward Traceability
|
protected |
|
protected |
Port-dependent event-queue type (often QEQueue).
Details
The type of the queue depends on the underlying operating system or 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.
Forward Traceability
|
private |
|
private |
|
private |