QF/C platform-independent public interface. More...
Go to the source code of this file.
Classes | |
class | QPSet |
Priority Set of up to QF_MAX_ACTIVE elements. More... | |
class | QActive |
Active object class (based on the QHsm implementation strategy) More... | |
struct | QActiveVtable |
Virtual table for the QActive class. More... | |
class | QMActive |
Active object class (based on QMsm implementation strategy) More... | |
class | QTimeEvt |
Time Event class. More... | |
class | QTicker |
"Ticker" Active Object class More... | |
class | QF |
QF active object framework. More... | |
Macros | |
#define | QF_NO_MARGIN ((uint_fast16_t)0xFFFFU) |
#define | Q_PRIO(prio_, pthre_) ((QPrioSpec)((prio_) | ((pthre_) << 8U))) |
#define | Q_NEW(evtT_, sig_, ...) |
#define | Q_NEW_X(e_, evtT_, margin_, sig_, ...) |
#define | Q_NEW_REF(evtRef_, evtT_) ((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_))) |
#define | Q_DELETE_REF(evtRef_) |
#define | QACTIVE_START(me_, prioSpec_, qSto_, qLen_, stkSto_, stkSize_, par_) |
#define | QACTIVE_POST(me_, e_, sender_) |
#define | QACTIVE_POST_X(me_, e_, margin_, sender_) |
#define | QACTIVE_POST_LIFO(me_, e_) |
#define | QACTIVE_PUBLISH(e_, sender_) (QActive_publish_((e_), (void const *)(sender_), (sender_)->prio)) |
#define | QTIMEEVT_TICK_X(tickRate_, sender_) (QTimeEvt_tick_((tickRate_), (sender_))) |
#define | QTIMEEVT_TICK(sender_) QTIMEEVT_TICK_X(0U, (sender_)) |
#define | QF_CRIT_EXIT_NOP() ((void)0) |
#define | QF_TICK_X(tickRate_, sender_) QTIMEEVT_TICK_X((tickRate_), (sender_)) |
#define | QF_TICK(sender_) QTIMEEVT_TICK(sender_) |
#define | QF_PUBLISH(e_, sender_) QACTIVE_PUBLISH((e_), (sender_)) |
Typedefs | |
typedef uint32_t | QPSetBits |
typedef uint32_t | QTimeEvtCtr |
typedef uint16_t | QPrioSpec |
typedef uint_fast16_t | QSchedStatus |
typedef QPSet | QSubscrList |
typedef QActiveVtable | QMActiveVtable |
Virtual Table for the QMActive class (inherited from QActiveVtable) | |
Functions | |
static void | QPSet_setEmpty (QPSet *const me) |
static bool | QPSet_isEmpty (QPSet const *const me) |
static bool | QPSet_notEmpty (QPSet const *const me) |
static bool | QPSet_hasElement (QPSet const *const me, uint_fast8_t const n) |
static void | QPSet_insert (QPSet *const me, uint_fast8_t const n) |
static void | QPSet_remove (QPSet *const me, uint_fast8_t const n) |
static uint_fast8_t | QPSet_findMax (QPSet const *const me) |
static void | QF_psInit (QSubscrList *const subscrSto, enum_t const maxSignal) |
Variables | |
QTimeEvt | QTimeEvt_timeEvtHead_ [QF_MAX_TICK_RATE] |
class QPSet |
The priority set represents the set of active objects that are ready to run and need to be considered by the scheduling algorithm. The set is capable of storing up to QF_MAX_ACTIVE priority levels, which can be configured in the rage 1..64, inclusive.
Class Members | ||
---|---|---|
QPSetBits volatile | bits |
bitmask with a bit for each element |
#define QF_NO_MARGIN ((uint_fast16_t)0xFFFFU) |
#define Q_PRIO | ( | prio_, | |
pthre_ | |||
) | ((QPrioSpec)((prio_) | ((pthre_) << 8U))) |
#define Q_NEW | ( | evtT_, | |
sig_, | |||
... | |||
) |
Asserting allocate a dynamic event (case when QEvt is not a POD)
#define Q_NEW_X | ( | e_, | |
evtT_, | |||
margin_, | |||
sig_, | |||
... | |||
) |
#define Q_NEW_REF | ( | evtRef_, | |
evtT_ | |||
) | ((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_))) |
Create a new reference of the current event e
The current event processed by an active object is available only for the duration of the run-to-completion (RTC) step. After that step, the current event is no longer available and the framework might recycle (garbage-collect) the event. The macro Q_NEW_REF() explicitly creates a new reference to the current event that can be stored and used beyond the current RTC step, until the reference is explicitly recycled by means of the macro Q_DELETE_REF().
[in,out] | evtRef_ | event reference to create |
[in] | evtT_ | event type (class name) of the event reference |
examples/win32/defer
illustrates the use of Q_NEW_REF()#define Q_DELETE_REF | ( | evtRef_ | ) |
Delete the event reference
Every event reference created with the macro Q_NEW_REF() needs to be eventually deleted by means of the macro Q_DELETE_REF() to avoid leaking the event.
[in,out] | evtRef_ | event reference to delete |
examples/win32/defer
illustrates the use of Q_DELETE_REF()#define QACTIVE_START | ( | me_, | |
prioSpec_, | |||
qSto_, | |||
qLen_, | |||
stkSto_, | |||
stkSize_, | |||
par_ | |||
) |
Virtual call to start an active object.
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 Active Object |
[in] | qSto_ | pointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue) |
[in] | qLen_ | length of the event queue (in events) |
[in] | stkSto_ | pointer to the stack storage (used only when per-AO stack is needed) |
[in] | stkSize_ | stack size (in bytes) |
[in] | par_ | pointer to the additional port-specific parameter(s) (might be NULL). |
#define QACTIVE_POST | ( | me_, | |
e_, | |||
sender_ | |||
) |
Invoke the direct event posting facility QActive_post_()
This macro asserts if the queue overflows and cannot accept the event.
[in,out] | me_ | current instance pointer (see oop) |
[in] | e_ | pointer to the event to post |
[in] | sender_ | pointer to the sender object. |
sendedr_
parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disenabled, the QACTIVE_POST() macro does not pass the sender_
parameter, so the overhead of passing this extra parameter is entirely avoided.#define QACTIVE_POST_X | ( | me_, | |
e_, | |||
margin_, | |||
sender_ | |||
) |
Invoke the direct event posting facility QActive_post_() without delivery guarantee
This macro does not assert if the queue overflows and cannot accept the event with the specified margin of free slots remaining.
[in,out] | me_ | current instance pointer (see oop) |
[in] | e_ | pointer to the event to post |
[in] | margin_ | the minimum free slots in the queue, which must still be available after posting the event. The special value QF_NO_MARGIN causes asserting failure in case event posting fails. |
[in] | sender_ | pointer to the sender object. |
sender_
parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the POST_X() macro does not pass the sender_
parameter, so the overhead of passing this extra parameter is entirely avoided.#define QACTIVE_POST_LIFO | ( | me_, | |
e_ | |||
) |
Virtual call to post an event to an active object using the Last-In-First-Out (LIFO) policy.
[in,out] | me_ | current instance pointer (see oop) |
[in] | e_ | pointer to the event to post |
#define QACTIVE_PUBLISH | ( | e_, | |
sender_ | |||
) | (QActive_publish_((e_), (void const *)(sender_), (sender_)->prio)) |
Publish an event to all subscriber Active Objects.
If Q_SPY is defined, this macro calls QActive_publish_() with the sender_
parameter to identify the publisher of the event. Otherwise, sender_
is not used.
[in] | e_ | pointer to the posted event |
[in] | sender_ | pointer to the sender object (actually used only when Q_SPY is defined) |
sender_
object is not necessarily a pointer to an active object. In fact, if QACTIVE_PUBLISH() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.#define QTIMEEVT_TICK_X | ( | tickRate_, | |
sender_ | |||
) | (QTimeEvt_tick_((tickRate_), (sender_))) |
Invoke the system clock tick processing QTimeEvt_tick_()
This macro is the recommended way of invoking clock tick processing, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.
[in] | tickRate_ | clock tick rate to be serviced through this call |
[in] | sender_ | pointer to the sender object. This parameter is actually only used when QS software tracing is enabled (macro Q_SPY is defined) |
sender
parameter, so the overhead of passing this extra parameter is entirely avoided.#define QTIMEEVT_TICK | ( | sender_ | ) | QTIMEEVT_TICK_X(0U, (sender_)) |
#define QF_CRIT_EXIT_NOP | ( | ) | ((void)0) |
No-operation for exiting a critical section
In some QF ports the critical section exit takes effect only on the next machine instruction. If this next instruction is another entry to a critical section, the critical section won't be really exited, but rather the two adjecent critical sections would be merged. The QF_CRIT_EXIT_NOP() macro contains minimal code required to prevent such merging of critical sections in such merging of critical sections in QF ports, in which it can occur.
#define QF_TICK_X | ( | tickRate_, | |
sender_ | |||
) | QTIMEEVT_TICK_X((tickRate_), (sender_)) |
Invoke the system clock tick processing
#define QF_TICK | ( | sender_ | ) | QTIMEEVT_TICK(sender_) |
Invoke the system clock tick processing for tick rate 0
#define QF_PUBLISH | ( | e_, | |
sender_ | |||
) | QACTIVE_PUBLISH((e_), (sender_)) |
Publish an event to all subscriber Active Objects.
typedef uint32_t QTimeEvtCtr |
typedef uint16_t QPrioSpec |
Priority specification for Active Objects in QP
Active Object priorities in QP are integer numbers in the range [1..QF_MAX_ACTIVE], whereas the special priority number 0 is reserved for the lowest-priority idle thread. The QP framework uses the direct priority numbering, in which higher numerical values denote higher urgency. For example, an AO with priority 32 has higher urgency than an AO with priority 23.
QPrioSpec allows an application developer to assign two priorities to a given AO (see also Q_PRIO()):
In the QP native preemptive kernels, like QK and QXK, the "preemption- threshold" priority is used as to implement the "preemption-threshold scheduling" (PTS). It determines the conditions under which a given thread can be preempted by other threads. Specifically, a given thread can be preempted only by another thread with a higher priority than the "preemption-threshold" of the original thread.
typedef uint_fast16_t QSchedStatus |
typedef QPSet QSubscrList |
typedef QActiveVtable QMActiveVtable |
|
inlinestatic |
|
inlinestatic |
|
inlinestatic |
|
inlinestatic |
|
inlinestatic |
insert element n
into the set (n = 1..QF_MAX_ACTIVE)
|
inlinestatic |
Remove element n
from the set (n = 1U..QF_MAX_ACTIVE)
|
inlinestatic |
|
inlinestatic |
initialization of publish-subscribe
|
extern |
heads of linked lists of time events, one for every clock tick rate