Active object class (based on the QHsm implementation strategy)
More...
#include "qp.h"
|
void | QActive_setAttr (QActive *const me, uint32_t attr1, void const *attr2) |
|
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.
|
|
|
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)
|
|
|
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
|
|
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.
- Note
QActive
is not intended to be instantiated directly, but rather serves as the abstract base class for derivation of active objects in the applications.
- See also
-
- Backward Traceability
- SDS_QP_QF : QF Active Object Framework
- SDS_QP_QActive : QActive Active Object class.
- QHsm : Hierarchical State Machine class (QHsm-style state machine implementation strategy)
- Usage
- The following example illustrates how to derive an active object from QActive.
typedef struct {
} Blinky;
. . .
void Blinky_ctor(Blinky * const me) {
QTimeEvt_ctorX(&me->timeEvt, &me->super, TIMEOUT_SIG, 0U);
}
#define Q_STATE_CAST(handler_)
Perform cast to QStateHandler.
Active object class (based on the QHsm implementation strategy)
void QActive_ctor(QActive *const me, QStateHandler const initial)
QActive constructor (abstract base class)
Definition at line 779 of file qp.h.
◆ QActive_ctor()
QActive constructor (abstract base class)
- Parameters
-
[in,out] | me | current instance pointer (see Object Orientation) |
[in] | initial | pointer to the top-most initial state-handler function in the derived active object |
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
◆ QActive_setAttr()
void QActive_setAttr |
( |
QActive *const | me, |
|
|
uint32_t | attr1, |
|
|
void const * | attr2 ) |
Generic setting of additional attributes (defined in some QP ports)
- Backward Traceability
-
◆ QActive_start()
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.
- Parameters
-
[in,out] | me | current instance pointer (see Object Orientation) |
[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) |
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
- DVR_QP_MC4_R08_13 : Rule 8.13(Advisory): A pointer should point to a const-qualified type whenever possible
- Usage
- The following example shows starting an AO when a per-task stack is NOT needed:
int main() {
QF_init();
BSP_init();
. . .
Blinky_ctor();
1U,
l_blinkyQSto,
(void *)0,
0U,
(void *)0);
. . .
return QF_run();
}
QEvt const * QEvtPtr
Pointer to const event instances passed around in QP Framework.
QP/C interface including the backwards-compatibility layer.
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.
Definition at line 276 of file qv.c.
◆ QActive_stop()
void QActive_stop |
( |
QActive *const | me | ) |
|
|
protected |
Stops execution of an active object and removes it from the framework's supervision.
- Parameters
-
- 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.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
◆ QActive_register_()
void QActive_register_ |
( |
QActive *const | me | ) |
|
|
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().
- Parameters
-
- Precondition
qf_qact:100
- the "QF-priority" of the AO must be in range (must be set before calling QActive_register_())
- the "QF-priority" must not be already in use (unique priority)
- the "QF-priority" must not exceed the "preemption-threshold"
- Postcondition
qf_qact:190
- the preceding pre-thre must not exceed the preemption-threshold
- the preemption-threshold must not exceed the next preemption-threshold
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 90 of file qf_qact.c.
◆ QActive_unregister_()
void QActive_unregister_ |
( |
QActive *const | me | ) |
|
|
private |
Un-register the active object from the framework.
- Details
- 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.
- Parameters
-
[in] | me | pointer to the active object to remove from the framework. |
- Precondition
qf_qact:200
- the priority of the active object must not be zero and cannot exceed the maximum QF_MAX_ACTIVE
- the priority of the AO must be already registered.
- Note
- The active object that is removed from the framework can no longer participate in any event exchange.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 142 of file qf_qact.c.
◆ QActive_post_()
bool QActive_post_ |
( |
QActive *const | me, |
|
|
QEvt const *const | e, |
|
|
uint_fast16_t const | margin, |
|
|
void const *const | sender ) |
|
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().
- Parameters
-
[in,out] | me | current instance pointer (see Object Orientation) |
[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) |
- Returns
- 'true' (success) if the posting succeeded (with the provided margin) and 'false' (failure) when the posting fails.
- Precondition
qf_actq:102
- the event pointer must be valid
- check internal event integrity (QP FuSa Subsystem)
- Postcondition
qf_actq:110
-
- Attention
- For
margin
== QF_NO_MARGIN, this function will assert internally if the event posting fails. In that case, it is unnecessary to check the return value from this function.
- Note
- This function should be called only through the macro QACTIVE_POST(). The reason is that the last parameter (
sender
) is needed only for software tracing, and typically is only defined when software tracing is enabled. When software tracing is disabled, the macro QACTIVE_POST() does not use the sender
parameter, so it might not be defined.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
- DVP_QS_MC4_R15_05 : Rule 15.5(Advisory): A function should have a single point of exit at the end
- Usage
QState Philo_hungry(Philo *
const me,
QEvt const *
const e) {
TableEvt *pe =
Q_NEW(TableEvt, HUNGRY_SIG);
pe->philNum = me->num;
break;
}
. . .
default: {
break;
}
}
return status;
}
#define Q_HANDLED()
Indicate that an action has been "handled". Applies to entry/exit actions and to internal transitions...
#define Q_NEW(evtT_, sig_,...)
Allocate a mutable (dynamic) event.
enum QStateRet QState
Type returned from state-handler functions.
#define Q_ENTRY_SIG
reserved signal sent to state handler to execute the entry case)
#define QACTIVE_POST(me_, e_, sender_)
Invoke the direct event posting facility QActive_post_().
#define Q_SUPER(super_)
Designates the superstate of a given state. Applicable only to QHsm subclasses.
QState QHsm_top(QHsm const *const me, QEvt const *const e)
QSignal sig
Signal of the event (see Event Signal)
◆ QActive_postLIFO_()
void QActive_postLIFO_ |
( |
QActive *const | me, |
|
|
QEvt const *const | e ) |
|
private |
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.
- Parameters
-
[in,out] | me | current instance pointer (see Object Orientation) |
[in] | e | pointer to the event to be posted |
- Precondition
qf_actq:200
- for the QXK kernel, postLIFO_() cannot be called from an extended thread
- Precondition
qf_actq:201
- the queue must be able to accept the event (cannot overflow)
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
- DVP_QS_MC4_R15_05 : Rule 15.5(Advisory): A function should have a single point of exit at the end
- Note
- This function might be implemented differently in various QP/C ports. The provided implementation assumes that the QEQueue class is used for the QActive event queue.
- See also
-
Definition at line 244 of file qf_actq.c.
◆ QActive_get_()
Get an event from the event queue of an active object.
- Details
- This function is only for internal use inside the QP Framework and QP 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.
- Parameters
-
- Returns
- A pointer to the received event. The returned pointer is guaranteed to be valid (can't be NULL).
- Note
- This function might be implemented differently in various QP/C ports. The provided implementation assumes that the QEQueue class is used for the QActive event queue.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 355 of file qf_actq.c.
◆ QActive_psInit()
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.
- Note
- To avoid any unexpected re-ordering of events posted into AO queues, the event multicasting is performed with scheduler locked. However, the scheduler is locked only up to the priority level of the highest-priority subscriber, so any AOs of even higher priority, which did not subscribe to this event are not affected.
- Backward Traceability
- SDS_QA_START : QA Application startup sequence
- QActive : Active object class (based on the QHsm implementation strategy)
◆ QActive_publish_()
void QActive_publish_ |
( |
QEvt const *const | e, |
|
|
void const *const | sender, |
|
|
uint_fast8_t const | qsId ) |
|
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.
- Precondition
qf_ps:200
- the published signal must be within the configured range
- Precondition
qf_ps:202
- check the integrity of the subscriber set (QP FuSa Subsystem)
- Note
- To avoid any unexpected re-ordering of events posted into AO queues, the event multicasting is performed with scheduler locked. However, the scheduler is locked only up to the priority level of the highest-priority subscriber, so any AOs of even higher priority, which did not subscribe to this event are not affected.
- Attention
- This operation is typically used via macro QACTIVE_PUBLISH(). This is because the last parameter
qsId
might be defined/provided only in the Spy build configuration (see Q_SPY). The macro ignores the qsId
parameter outside the Spy configuration, so the same code builds correctly in all configurations.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
- Usage
QState Philo_eating(Philo *
const me,
QEvt const *
const e) {
. . .
TableEvt
const *pe =
Q_NEW(TableEvt, DONE_SIG, me->id);
break;
}
. . .
}
return status_;
}
@ Q_RET_HANDLED
event handled (internal transition)
#define QACTIVE_PUBLISH(e_, sender_)
Publish an event to all subscriber Active Objects.
#define Q_EXIT_SIG
reserved signal sent to state handler to execute the exit case)
Definition at line 87 of file qf_ps.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.
- 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.
- Parameters
-
[in,out] | me | current instance pointer (see Object Orientation) |
[in] | sig | event signal to subscribe |
- Precondition
qf_ps:300
- signal must be in range of subscribe signals
- subscriber AO priority must be in range
- the AO must be registered (started)
- Precondition
qf_ps:302
- check the integrity of the subscriber set (QP FuSa Subsystem)
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
- 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) {
for (uint8_t n = 0U; n < N; ++n) {
me->fork[n] = FREE;
me->isHungry[n] = false;
}
return Q_TRAN(&Table_serving);
}
#define Q_UNUSED_PAR(par_)
Helper macro to clearly mark unused parameters of functions.
#define Q_TRAN(target_)
Take transition to the specified target_ state.
void QActive_subscribe(QActive const *const me, enum_t const sig)
Subscribes for delivery of signal sig to the active object.
Definition at line 196 of file qf_ps.c.
◆ QActive_unsubscribe()
void QActive_unsubscribe |
( |
QActive const *const | me, |
|
|
enum_t const | sig ) |
|
protected |
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.
- Parameters
-
[in,out] | me | current instance pointer (see Object Orientation) |
[in] | sig | event signal to unsubscribe |
- Precondition
qf_ps:400
- signal must be in range of subscribe signals
- subscriber AO priority must be in range
- the AO must be registered (started)
- Precondition
qf_ps:402
- check the integrity of the subscriber set (QP FuSa Subsystem)
- 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.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 235 of file qf_ps.c.
◆ QActive_unsubscribeAll()
void QActive_unsubscribeAll |
( |
QActive const *const | me | ) |
|
|
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.
- Parameters
-
- Precondition
qf_ps:500
- subscriber AO priority must be in range
- the AO must be registered (started)
- 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.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 274 of file qf_ps.c.
◆ QActive_defer()
bool QActive_defer |
( |
QActive const *const | me, |
|
|
struct QEQueue *const | eq, |
|
|
QEvt const *const | e ) |
|
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.
- Parameters
-
[in,out] | me | current instance pointer (see Object Orientation) |
[in] | eq | pointer to a "raw" thread-safe queue to recall an event from. |
[in] | e | pointer 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.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
◆ QActive_recall()
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.
- Parameters
-
[in,out] | me | current instance pointer (see Object Orientation) |
[in] | eq | pointer 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.
- Backward Traceability
-
Definition at line 84 of file qf_defer.c.
◆ QActive_flushDeferred()
uint_fast16_t QActive_flushDeferred |
( |
QActive const *const | me, |
|
|
struct QEQueue *const | eq, |
|
|
uint_fast16_t const | num ) |
|
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.
- Parameters
-
[in,out] | me | current instance pointer (see Object Orientation) |
[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) |
- Returns
- the number of events actually flushed from the queue.
- Backward Traceability
-
Definition at line 145 of file qf_defer.c.
◆ QActive_evtLoop_()
void QActive_evtLoop_ |
( |
QActive *const | me | ) |
|
|
private |
Event loop thread routine for executing an active object act
(defined some in QP ports)
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
◆ super
Definition at line 781 of file qp.h.
◆ prio
QF-priority [1..QF_MAX_ACTIVE] of this AO.
- See also
-
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 784 of file qp.h.
◆ pthre
Preemption-threshold [1..QF_MAX_ACTIVE] of this AO.
- See also
-
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 787 of file qp.h.
◆ thread
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 store the thread handle. In other ports me->thread can be a pointer to the Thread-Local-Storage (TLS).
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 791 of file qp.h.
◆ osObject
Port-dependent per-thread object.
- Details
- This data might be used in various ways, depending on the QF port. In some ports me->osObject is used to block the calling thread when the native QF queue is empty. In other QF ports the OS-dependent object might be used differently.
Definition at line 796 of file qp.h.
◆ eQueue
Port-dependent event-queue type (often QEQueue)
- Details
- 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.
- Note
- The native QF event queue is configured by defining the macro QACTIVE_EQUEUE_TYPE as QEQueue.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 801 of file qp.h.
◆ prio_dis
Definition at line 806 of file qp.h.
◆ pthre_dis
Definition at line 811 of file qp.h.
◆ QActive_registry_
Static (one per-class) array of registered active objects.
Definition at line 818 of file qp.h.
◆ QActive_subscrList_
Static (one per-class) pointer to all subscriber AOs for a given event signal.
- Backward Traceability
- QActive : Active object class (based on the QHsm implementation strategy)
Definition at line 821 of file qp.h.
◆ QActive_maxPubSignal_
Static (one per-class) maximum published signal (the size of the subscrList_ array)
Definition at line 824 of file qp.h.
The documentation for this class was generated from the following files: