QF/C platform-independent public interface. More...

#include "qpset.h"

Include dependency graph for qf.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	QActive
	Active Object (based on QHsm implementation) More...

struct	QActiveVtbl
	Virtual table for the QActive class. More...

struct	QTimeEvt
	Time Event structure. More...

Macros
#define	QF_EVENT_SIZ_SIZE 2
	Default value of the macro configurable value in qf_port.h. More...

#define	QF_MAX_EPOOL 3
	Default value of the macro configurable value in qf_port.h. More...

#define	QF_MAX_TICK_RATE 1
	Default value of the macro configurable value in qf_port.h. More...

#define	QF_TIMEEVT_CTR_SIZE 2
	macro to override the default QTimeEvtCtr size. More...

#define	QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, par_)
	Polymorphically start an active object. More...

#define	QACTIVE_POST(me_, e_, sender_)
	Polymorphically posts an event to an active object (FIFO) with delivery guarantee. More...

#define	QACTIVE_POST_X(me_, e_, margin_, sender_)
	Polymorphically posts an event to an active object (FIFO) without delivery guarantee. More...

#define	QACTIVE_POST_LIFO(me_, e_) ((((QActiveVtbl const )((me_)->super.vptr))->postLIFO)((me_), (e_)))
	Polymorphically posts an event to an active object using the Last-In-First-Out (LIFO) policy. More...

#define	QF_PUBLISH(e_, sender_) (QF_publish_((e_), (void const *)(sender_)))
	Invoke the event publishing facility QF_publish_(). More...

#define	QF_TICK_X(tickRate_, sender_) (QF_tickX_((tickRate_), (sender_)))
	Invoke the system clock tick processing QF_tickX_(). More...

#define	QF_NO_MARGIN ((uint_fast16_t)0xFFFF)
	special value of margin that causes asserting failure in case event allocation or event posting fails More...

#define	QF_TICK(sender_) QF_TICK_X((uint_fast8_t)0, (sender_))
	Invoke the system clock tick processing for rate 0. More...

#define	Q_NEW(evtT_, sig_)
	Allocate a dynamic event. More...

#define	Q_NEW_X(e_, evtT_, margin_, sig_)
	Allocate a dynamic event (non-asserting version). More...

#define	Q_NEW_REF(evtRef_, evtT_) ((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_)))
	Create a new reference of the current event `e` More...

#define	Q_DELETE_REF(evtRef_)
	Delete the event reference. More...

#define	QF_CRIT_EXIT_NOP() ((void)0)
	No-operation for exiting a critical section. More...

#define	QF_getVersion() (QP_versionStr)
	get the current QF version number string of the form "X.Y.Z" More...

Typedefs
typedef uint16_t	QEvtSize
	The data type to store the block-size defined based on the macro QF_EVENT_SIZ_SIZE. More...

typedef QActive	QMActive
	QMActive active object (based on QMsm implementation) More...

typedef QActiveVtbl	QMActiveVtbl
	Virtual Table for the QMActive class (inherited from QActiveVtbl. More...

typedef uint16_t	QTimeEvtCtr
	type of the Time Event counter, which determines the dynamic range of the time delays measured in clock ticks. More...

typedef QPSet	QSubscrList
	Subscriber-List structure. More...

typedef QActive	QTicker
	QTicker Active Object class. More...

Functions
void	QActive_ctor (QActive *const me, QStateHandler initial)
	protected "constructor" of an QActive active object More...

void	QActive_subscribe (QActive const *const me, enum_t const sig)
	Subscribes for delivery of signal `sig` to the active object `me`. More...

void	QActive_unsubscribe (QActive const *const me, enum_t const sig)
	Un-subscribes from the delivery of signal `sig` to the AO `me`. More...

void	QActive_unsubscribeAll (QActive const *const me)
	Un-subscribes from the delivery of all signals to the AO `me`. More...

bool	QActive_defer (QActive const const me, QEQueue const eq, QEvt const *const e)
	Defer an event `e` to a given event queue `eq`. More...

bool	QActive_recall (QActive const me, QEQueue const eq)
	Recall a deferred event from a given event queue `eq`. More...

uint_fast16_t	QActive_flushDeferred (QActive const const me, QEQueue const eq)
	Flush the specified deferred queue `eq`. More...

void	QActive_setAttr (QActive const me, uint32_t attr1, void const attr2)
	Generic setting of additional attributes (useful in QP ports) More...

void	QMActive_ctor (QMActive *const me, QStateHandler initial)
	protected "constructor" of an QMActive active object. More...

void	QTimeEvt_ctorX (QTimeEvt const me, QActive const act, enum_t const sig, uint_fast8_t tickRate)
	The extended "constructor" to initialize a Time Event. More...

void	QTimeEvt_armX (QTimeEvt *const me, QTimeEvtCtr const nTicks, QTimeEvtCtr const interval)
	Arm a time event (one shot or periodic) for direct event posting. More...

bool	QTimeEvt_rearm (QTimeEvt *const me, QTimeEvtCtr const nTicks)
	Rearm a time event. More...

bool	QTimeEvt_disarm (QTimeEvt *const me)
	Disarm a time event. More...

bool	QTimeEvt_wasDisarmed (QTimeEvt *const me)
	Check the "was disarmed" status of a time event. More...

QTimeEvtCtr	QTimeEvt_ctr (QTimeEvt const *const me)
	Get the current value of the down-counter of a time event. More...

void	QF_init (void)
	QF initialization. More...

void	QF_psInit (QSubscrList *const subscrSto, enum_t const maxSignal)
	Publish-subscribe initialization. More...

void	QF_poolInit (void *const poolSto, uint_fast32_t const poolSize, uint_fast16_t const evtSize)
	Event pool initialization for dynamic allocation of events. More...

uint_fast16_t	QF_poolGetMaxBlockSize (void)
	Obtain the block size of any registered event pools. More...

int_t	QF_run (void)
	Transfers control to QF to run the application. More...

void	QF_stop (void)
	Function invoked by the application layer to stop the QF application and return control to the OS/Kernel. More...

void	QF_onStartup (void)
	Startup QF callback. More...

void	QF_onCleanup (void)
	Cleanup QF callback. More...

void	QF_publish_ (QEvt const const e, void const const sender)
	Publish event to the framework. More...

void	QF_tickX_ (uint_fast8_t const tickRate, void const *const sender)
	Processes all armed time events at every clock tick. More...

bool	QF_noTimeEvtsActiveX (uint_fast8_t const tickRate)
	Returns 'true' if there are no armed time events at a given tick rate. More...

void	QF_add_ (QActive *const a)
	Register an active object to be managed by the framework. More...

void	QF_remove_ (QActive *const a)
	Remove the active object from the framework. More...

uint_fast16_t	QF_getPoolMin (uint_fast8_t const poolId)
	Obtain the minimum of free entries of the given event pool. More...

uint_fast16_t	QF_getQueueMin (uint_fast8_t const prio)
	This function returns the minimum of free entries of the given event queue. More...

QEvt *	QF_newX_ (uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)
	Internal QF implementation of creating new dynamic event. More...

QEvt const *	QF_newRef_ (QEvt const const e, void const const evtRef)
	Internal QF implementation of creating new event reference. More...

void	QF_deleteRef_ (void const *const evtRef)
	Internal QF implementation of deleting event reference. More...

void	QF_gc (QEvt const *const e)
	Recycle a dynamic event. More...

void	QF_bzero (void *const start, uint_fast16_t len)
	Clear a specified region of memory to zero. More...

void	QTicker_ctor (QTicker *const me, uint8_t tickRate)
	Constructor of the QTicker Active Object class. More...

Variables
QActive *	QF_active_ [QF_MAX_ACTIVE+1]
	array of registered active objects More...

Detailed Description

QF/C platform-independent public interface.

Definition in file qf.h.

Data Structure Documentation

◆ QActive

struct QActive

Active Object (based on QHsm implementation)

Description: 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.

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 Object Orientation).
typedef struct {
QActive super; /* inherits QActive */
QTimeEvt timeEvt; /* to timeout thining or eating */
uint8_t num; /* this philosopher's number */
} Philo;

Definition at line 114 of file qf.h.

Collaboration diagram for QActive:

Data Fields
QHsm	super	inherits QHsm
uint8_t	prio	QF priority (1..QF_MAX_ACTIVE) of this active object.

◆ QTimeEvt

struct QTimeEvt

Time Event structure.

Description: Time events are special QF events equipped with the notion of time passage. The basic usage model of the time events is as follows. An active object allocates one or more QTimeEvt objects (provides the storage for them). When the active object needs to arrange for a timeout, it arms one of its time events to fire either just once (one-shot) or periodically. Each time event times out independently from the others, so a QF application can make multiple parallel timeout requests (from the same or different active objects). When QF detects that the appropriate moment has arrived, it inserts the time event directly into the recipient's event queue. The recipient then processes the time event just like any other event.

Time events, as any other QF events derive from the QEvt base structure. Typically, you will use a time event as-is, but you can also further derive more specialized time events from it by adding some more data members and/or specialized functions that operate on the specialized time events.

Internally, the armed time events are organized into linked lists–one list for every supported ticking rate. These linked lists are scanned in every invocation of the QF_tickX_() function. Only armed (timing out) time events are in the list, so only armed time events consume CPU cycles.

See also: QTimeEvt for the description of the data members
Object Orientation

Note: QF manages the time events in the function QF_tickX_(), which must be called periodically, from the clock tick ISR or from the special QTicker active object.; Even though QTimeEvt is a subclass of QEvt, QTimeEvt instances can NOT be allocated dynamically from event pools. In other words, it is illegal to allocate QTimeEvt instances with the Q_NEW() or Q_NEW_X() macros.

Definition at line 437 of file qf.h.

Collaboration diagram for QTimeEvt:

Data Fields
QEvt	super
struct QTimeEvt *volatile	next	link to the next time event in the list
void *volatile	act	the active object that receives the time events
QTimeEvtCtr volatile	ctr	the internal down-counter of the time event. Description The down-counter is decremented by 1 in every QF_tickX_() invocation. The time event fires (gets posted or published) when the down-counter reaches zero.
QTimeEvtCtr	interval	the interval for periodic time event (zero for one-shot time event) Description The value of the interval is re-loaded to the internal down-counter when the time event expires, so that the time event keeps timing out periodically.

Macro Definition Documentation

◆ QF_EVENT_SIZ_SIZE

#define QF_EVENT_SIZ_SIZE 2

Default value of the macro configurable value in qf_port.h.

Definition at line 50 of file qf.h.

◆ QF_MAX_EPOOL

#define QF_MAX_EPOOL 3

Default value of the macro configurable value in qf_port.h.

Definition at line 70 of file qf.h.

◆ QF_MAX_TICK_RATE

#define QF_MAX_TICK_RATE 1

Default value of the macro configurable value in qf_port.h.

Valid values: [0..15]; default 1

Definition at line 77 of file qf.h.

◆ QF_TIMEEVT_CTR_SIZE

#define QF_TIMEEVT_CTR_SIZE 2

macro to override the default QTimeEvtCtr size.

Valid values: 1, 2, or 4; default 2

Definition at line 86 of file qf.h.

◆ QACTIVE_START

#define QACTIVE_START	(	me_,
		prio_,
		qSto_,
		qLen_,
		stkSto_,
		stkLen_,
		par_
	)

Value:

do { \
    Q_ASSERT((me_)->super.vptr);                                             \
    (*((QActiveVtbl const *)((me_)->super.vptr))->start)(                    \
        (me_), (prio_), (qSto_), (qLen_), (stkSto_), (stkLen_), (par_));     \
} while (0)

Polymorphically start an active object.

Description: Starts execution of the AO and registers the AO with the framework.

Parameters

[in,out]	me_	pointer (see Object Orientation)
[in]	prio_	priority at which to start 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).

Usage: #include "qpc.h"
Q_DEFINE_THIS_FILE
int main() {
static Philo l_philo[N]; /* N Philo active objects */
static QEvt const *l_philQueueSto[N][N]; /* storage for event queues */
static int l_philoStk[N][256]; /* stacks for the Philo active objects */
. . .
for (n = 0; n < N; ++n) {
TableEvt ie; /* initialization event for the Philo SM */
ie.philNum = n;
Philo_ctor(&l_philo[n]);
QACTIVE_START((QActive *)&l_philo[n], /* Philo pointer */
(uint_fast8_t)(n*10 + 1), /* priority */
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]), /* queue */
l_philoStk[n], sizeof(l_philoStk[n]), /* per AO stack */
&ie.super); /* initialization event */
}
. . .
}

Definition at line 215 of file qf.h.

◆ QACTIVE_POST

#define QACTIVE_POST	(	me_,
		e_,
		sender_
	)

Value:

((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \

(e_), QF_NO_MARGIN, (sender_)))

QActiveVtbl

Virtual table for the QActive class.

Definition: qf.h:170

QF_NO_MARGIN

#define QF_NO_MARGIN

special value of margin that causes asserting failure in case event allocation or event posting fails

Definition: qf.h:632

Polymorphically posts an event to an active object (FIFO) with delivery guarantee.

Description: This macro asserts if the queue overflows and cannot accept the event.

Parameters

[in,out]	me_	pointer (see Object Orientation)
[in]	e_	pointer to the event to post
[in]	sender_	pointer to the sender object.

Note: The 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_ argument, so the overhead of passing this extra argument is entirely avoided.; The pointer to the sender object is not necessarily a pointer to an active object. In fact, if QACTIVE_POST() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.

See also: QACTIVE_POST_X, QActive_post_().

Definition at line 247 of file qf.h.

◆ QACTIVE_POST_X

#define QACTIVE_POST_X	(	me_,
		e_,
		margin_,
		sender_
	)

Value:

((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \

(e_), (margin_), (sender_)))

QActiveVtbl

Virtual table for the QActive class.

Definition: qf.h:170

Polymorphically posts an event to an active object (FIFO) without delivery guarantee.

Description: This macro does not assert if the queue overflows and cannot accept the event with the specified margin of free slots remaining.

Parameters

[in,out]	me_	pointer (see Object Orientation)
[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 allocation fails.
[in]	sender_	pointer to the sender object.

Returns: 'true' if the posting succeeded, and 'false' if the posting failed due to insufficient margin of free slots available in the queue.

Note: The sender_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the QACTIVE_POST() macro does not pass the sender_ argument, so the overhead of passing this extra argument is entirely avoided.; The pointer to the sender object is not necessarily a pointer to an active object. In fact, if QACTIVE_POST_X() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.

Usage: extern QActive *AO_Table;
. . .
/* typically inside a state machine action */
TableEvt *pe;
Q_NEW_X(pe, TableEvt, 5U, HUNGRY_SIG); /* dynamic alloc, margin==5 */
if (pe != (TableEvt *)0) {
pe->philNum = me->num;
QACTIVE_POST_X(AO_Table, &pe->super, 3U, me); /* margin==3 */
}
. . .

Definition at line 285 of file qf.h.

◆ QACTIVE_POST_LIFO

#define QACTIVE_POST_LIFO	(	me_,
		e_
	)	((((QActiveVtbl const )((me_)->super.vptr))->postLIFO)((me_), (e_)))

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

Parameters

[in,out]	me_	pointer (see Object Orientation)
[in]	e_	pointer to the event to post

Definition at line 306 of file qf.h.

◆ QF_PUBLISH

#define QF_PUBLISH	(	e_,
		sender_
	)	(QF_publish_((e_), (void const *)(sender_)))

Invoke the event publishing facility QF_publish_().

Description: This macro is the recommended way of publishing events, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.

Parameters

[in]	e_	pointer to the posted event
[in]	sender_	pointer to the sender object. This argument is actually only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the macro calls QF_publish_() without the `sender_` parameter, so the overhead of passing this extra argument is entirely avoided.

Note: the pointer to the sender object is not necessarily a pointer to an active object. In fact, if QF_PUBLISH() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the publisher of the event.

See also: QF_publish_().

Definition at line 577 of file qf.h.

◆ QF_TICK_X

#define QF_TICK_X	(	tickRate_,
		sender_
	)	(QF_tickX_((tickRate_), (sender_)))

Invoke the system clock tick processing QF_tickX_().

Description: 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.

Parameters

[in]	tickRate	clock tick rate to be serviced through this call
[in]	sender	pointer to the sender object. This argument is actually only used when QS software tracing is enabled (macro Q_SPY is defined)

Note: When QS software tracing is disabled, the macro calls QF_tickX_() without the sender parameter, so the overhead of passing this extra argument is entirely avoided.; The pointer to the sender object is not necessarily a pointer to an active object. In fact, when QF_TICK_X() is called from an interrupt, you would create a unique object just to unambiguously identify the ISR as the sender of the time events.

Usage: The following example shows how to invoke QF_TICK_X() for different system tick rates:
/* case 1: Interrupt Controller available,
* "unconditional interrupt unlocking" critical section policy
* (nesting of critical sections _not_ allowed)
*/
interrupt void ISR_timer() { /* entered with interrupts disabled in hardware */
QF_INT_ENABLE(); /* enable interrupts */
QF_TICK_X(0U, &l_ISR_timer); /*<-- QF tick processing for rate 0 */
QF_INT_DISABLE(); /* disable interrupts again */
/* send the EOI instruction to the Interrupt Controller */
}
/* case 2: Interrupt Controller not used,
* "saving and restoring interrupt status" critical section policy
* (nesting of critical sections allowed)
*/
interrupt void ISR_timer() {
QF_TICK_X(1U, &l_ISR_timer); /*<-- QF tick processing for rate 1 */
}

See also: QF_tickX_().

Definition at line 620 of file qf.h.

◆ QF_NO_MARGIN

#define QF_NO_MARGIN ((uint_fast16_t)0xFFFF)

special value of margin that causes asserting failure in case event allocation or event posting fails

Definition at line 632 of file qf.h.

◆ QF_TICK

#define QF_TICK ( sender_ ) QF_TICK_X((uint_fast8_t)0, (sender_))

Invoke the system clock tick processing for rate 0.

Definition at line 635 of file qf.h.

◆ Q_NEW

#define Q_NEW	(	evtT_,
		sig_
	)

Value:

((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \

QF_NO_MARGIN, (sig_)))

uint_fast16_t

unsigned int uint_fast16_t

fast at-least 16-bit unsigned int

Definition: stdint.h:38

QF_newX_

QEvt * QF_newX_(uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)

Internal QF implementation of creating new dynamic event.

Definition: qf_dyn.c:163

QF_NO_MARGIN

#define QF_NO_MARGIN

special value of margin that causes asserting failure in case event allocation or event posting fails

Definition: qf.h:632

Allocate a dynamic event.

Description: The macro calls the internal QF function QF_newX_() with margin == QF_NO_MARGIN, which causes an assertion when the event cannot be successfully allocated.

Parameters

[in]	evtT_	event type (class name) of the event to allocate
[in]	sig_	signal to assign to the newly allocated event

Returns: a valid event pointer cast to the type evtT_.

Note: If #Q_EVT_CTOR is defined, the Q_NEW() macro becomes variadic and takes all the arguments needed by the constructor of the event class being allocated. The constructor is then called by means of the placement-new operator.

Usage: The following example illustrates dynamic allocation of an event:
extern QActive *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); /* direct posting */
status = Q_HANDLED();
break;
}
. . .
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}

Definition at line 701 of file qf.h.

◆ Q_NEW_X

#define Q_NEW_X	(	e_,
		evtT_,
		margin_,
		sig_
	)

Value:

((e_) = \

(evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), (margin_), (sig_)))

uint_fast16_t

unsigned int uint_fast16_t

fast at-least 16-bit unsigned int

Definition: stdint.h:38

QF_newX_

QEvt * QF_newX_(uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)

Internal QF implementation of creating new dynamic event.

Definition: qf_dyn.c:163

Allocate a dynamic event (non-asserting version).

Description: This macro allocates a new event and sets the pointer e_, while leaving at least margin_ of events still available in the pool

Parameters

[in]	evtT_	event type (class name) of the event to allocate
[in]	margin_	number of events that must remain available in the given pool after this allocation. The special value QF_NO_MARGIN causes asserting failure in case event allocation or event posting fails.
[in]	sig_	signal to assign to the newly allocated event

Returns: an event pointer cast to the type evtT_ or NULL if the event cannot be allocated with the specified margin.

Note: If #Q_EVT_CTOR is defined, the Q_NEW_X() macro becomes variadic and takes all the arguments needed by the constructor of the event class being allocated. The constructor is then called and all the extra arguments are passed to it.

Usage: The following example illustrates dynamic allocation of an event:
extern QActive *AO_Table;
. . .
/* typically inside a state machine action */
TableEvt *pe;
Q_NEW_X(pe, TableEvt, 5U, HUNGRY_SIG); /* dynamic alloc, margin==5 */
if (pe != (TableEvt *)0) {
pe->philNum = me->num;
QACTIVE_POST_X(AO_Table, &pe->super, 3U, me); /* margin==3 */
}
. . .

Definition at line 731 of file qf.h.

◆ Q_NEW_REF

#define Q_NEW_REF	(	evtRef_,
		evtT_
	)	((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_)))

Create a new reference of the current event e

Description: 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().

Parameters

[in,out]	evtRef_	event reference to create
[in]	evtT_	event type (class name) of the event reference

Usage: The example defer in the directory examples/win32/defer illustrates the use of Q_NEW_REF()

See also: Q_DELETE_REF()

Definition at line 756 of file qf.h.

◆ Q_DELETE_REF

#define Q_DELETE_REF ( evtRef_ )

Value:

do { \
    QF_deleteRef_((evtRef_)); \
    (evtRef_) = (void *)0; \
} while (0)

Delete the event reference.

Description: 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.

Parameters

[in,out] evtRef_ event reference to delete

Usage: The example defer in the directory examples/win32/defer illustrates the use of Q_DELETE_REF()

See also: Q_NEW_REF()

Definition at line 774 of file qf.h.

◆ QF_CRIT_EXIT_NOP

#define QF_CRIT_EXIT_NOP ( ) ((void)0)

No-operation for exiting a critical section.

Description: 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 adjacent critical sections would be merged. The QF_CRIT_EXIT_NOP() macro contains minimal code required to prevent such merging of critical sections in QF ports, in which it can occur.

Definition at line 797 of file qf.h.

◆ QF_getVersion

#define QF_getVersion ( ) (QP_versionStr)

get the current QF version number string of the form "X.Y.Z"

Definition at line 825 of file qf.h.

Typedef Documentation

◆ QEvtSize

typedef uint16_t QEvtSize

The data type to store the block-size defined based on the macro QF_EVENT_SIZ_SIZE.

The dynamic range of this data type determines the maximum block size that can be managed by the pool.

Definition at line 61 of file qf.h.

◆ QMActive

typedef QActive QMActive

QMActive active object (based on QMsm implementation)

Description: QMActive represents an active object that uses the QMsm style state machine implementation strategy. This strategy requires the use of the QM modeling tool to generate state machine code automatically, but the code is faster than in the QHsm style implementation strategy and needs less run-time support (smaller event-processor).

Note: QMActive is not intended to be instantiated directly, but rather serves as the base class for derivation of active objects in the application.; QMActive inherits QActive exactly, without adding any new attributes (or operations) and therefore, QMActive is typedef'ed as QActive. QMActive is not intended to be instantiated directly, but rather serves as the base class for derivation of active objects in the application.

See also: QActive

Usage: The following example illustrates how to derive an active object from QMActive. Please note that the QActive member super is defined as the first member of the derived struct (see Object Orientation).
typedef struct {
QMActive super; /* inherits QMActive */
QTimeEvt timeEvt; /* to timeout thining or eating */
uint8_t num; /* this philosopher's number */
} Philo;

Definition at line 364 of file qf.h.

◆ QMActiveVtbl

typedef QActiveVtbl QMActiveVtbl

Virtual Table for the QMActive class (inherited from QActiveVtbl.

Note: QMActive inherits QActive exactly, without adding any new virtual functions and therefore, QMActiveVtbl is typedef'ed as QActiveVtbl.

Definition at line 372 of file qf.h.

◆ QTimeEvtCtr

typedef uint16_t QTimeEvtCtr

type of the Time Event counter, which determines the dynamic range of the time delays measured in clock ticks.

Description: This typedef is configurable via the preprocessor switch QF_TIMEEVT_CTR_SIZE. The other possible values of this type are as follows:
uint8_t when (QF_TIMEEVT_CTR_SIZE == 1), and
uint32_t when (QF_TIMEEVT_CTR_SIZE == 4).

Definition at line 393 of file qf.h.

◆ QSubscrList

typedef QPSet QSubscrList

Subscriber-List structure.

Description: This data type represents a set of active objects that subscribe to a given signal. The set is represented as a priority-set, where each bit corresponds to the unique priority of an active object.

See also: QSubscrList for the description of the data members

Definition at line 500 of file qf.h.

◆ QTicker

typedef QActive QTicker

QTicker Active Object class.

Description: The QTicker is an efficient active object specialized to process QF system clock tick at a specified tick frequency [0..QF_MAX_TICK_RATE]. Placing system clock tick processing in an active object allows you to remove the non-deterministic QF::TICK_X() processing from the interrupt level and move it into the thread-level, where you can prioritize it as low as you wish.

Definition at line 818 of file qf.h.

Function Documentation

◆ QActive_ctor()

void QActive_ctor	(	QActive *const	me,
		QStateHandler	initial
	)

protected "constructor" of an QActive active object

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

Parameters

[in,out]	me	pointer (see Object Orientation)
[in]	initial	pointer 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 66 of file qf_qact.c.

◆ QActive_subscribe()

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

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

Description: 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]	me	pointer (see Object Orientation)
[in]	sig	event 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) {
uint8_t n;
(void)e; /* suppress the compiler warning */
QActive_subscribe(&me->super, HUNGRY_SIG); /* subscribe to HUNGRY */
QActive_subscribe(&me->super, DONE_SIG); /*... to DONE */
QActive_subscribe(&me->super, TERMINATE_SIG); /*...and to TERMINATE */
for (n = 0; n < N; ++n) {
me->fork[n] = FREE;
me->isHungry[n] = 0;
}
return Q_TRAN(&Table_serving);
}

See also: QF_publish_(), QActive_unsubscribe(), and QActive_unsubscribeAll()

Definition at line 207 of file qf_ps.c.

◆ QActive_unsubscribe()

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

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

Description: 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]	me	pointer (see Object Orientation)
[in]	sig	event 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 255 of file qf_ps.c.

◆ QActive_unsubscribeAll()

void QActive_unsubscribeAll ( QActive const *const me )

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

Description: 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] me pointer (see Object Orientation)

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 304 of file qf_ps.c.

◆ QActive_defer()

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

Defer an event e to a given event queue eq.

Description: 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	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.

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

See also: QActive_recall(), QEQueue, QActive_flushDeferred()

Definition at line 77 of file qf_defer.c.

◆ QActive_recall()

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

Recall a deferred event from a given event queue eq.

Description: 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	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.

See also: QActive_recall(), QEQueue, QACTIVE_POST_LIFO()

Definition at line 118 of file qf_defer.c.

◆ QActive_flushDeferred()

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

Flush the specified deferred queue eq.

Description: 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	pointer (see Object Orientation)
[in]	eq	pointer 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 187 of file qf_defer.c.

◆ QActive_setAttr()

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

Generic setting of additional attributes (useful in QP ports)

◆ QMActive_ctor()

void QMActive_ctor	(	QMActive *const	me,
		QStateHandler	initial
	)

protected "constructor" of an QMActive active object.

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

Parameters

[in,out]	me	pointer (see Object Orientation)
[in]	initial	pointer to the event to be dispatched to the MSM

Note: Must be called only ONCE before QMSM_INIT().

See also: QHsm_ctor() and QFsm_ctor()

Note: QMActive inherits QActive, so by the Object Orientation convention it should call the constructor of the superclass, i.e., QActive_ctor(). However, this would pull in the QActiveVtbl, which in turn will pull in the code for QHsm_init_() and QHsm_dispatch_() implemetations, which is expensive. To avoid this code size penalty, in case QHsm is not used in a given project, the call to QMsm_ctor() avoids pulling in the code for QHsm.

Definition at line 67 of file qf_qmact.c.

◆ QTimeEvt_ctorX()

void QTimeEvt_ctorX	(	QTimeEvt *const	me,
		QActive *const	act,
		enum_t const	sig,
		uint_fast8_t	tickRate
	)

The extended "constructor" to initialize a Time Event.

Description: When creating a time event, you must commit it to a specific active object act, tick rate tickRate and event signal sig. You cannot change these attributes later.

Parameters

[in,out]	me	pointer (see Object Orientation)
[in]	act	pointer to the active object associated with this time event. The time event will post itself to this AO.
[in]	sig	signal to associate with this time event.
[in]	tickRate	systemclock tick rate to associate with this time event in the range [0..15].

Note: You should call the constructor exactly once for every Time Event object before arming the Time Event. The ideal place for initializing the time event(s) associated with a given AO is the AO's constructor.

Precondition: The signal must be valid and the tick rate in range

Definition at line 237 of file qf_time.c.

◆ QTimeEvt_armX()

void QTimeEvt_armX	(	QTimeEvt *const	me,
		QTimeEvtCtr const	nTicks,
		QTimeEvtCtr const	interval
	)

Arm a time event (one shot or periodic) for direct event posting.

Description: Arms a time event to fire in a specified number of clock ticks and with a specified interval. If the interval is zero, the time event is armed for one shot ('one-shot' time event). The time event gets directly posted (using the FIFO policy) into the event queue of the host active object.

Parameters

[in,out]	me	pointer (see Object Orientation)
[in]	nTicks	number of clock ticks (at the associated rate) to rearm the time event with.
[in]	interval	interval (in clock ticks) for periodic time event.

Note: After posting, a one-shot time event gets automatically disarmed while a periodic time event (interval != 0) is automatically re-armed.; A time event can be disarmed at any time by calling the QTimeEvt_disarm() function. Also, a time event can be re-armed to fire in a different number of clock ticks by calling the QTimeEvt_rearm() function.

Usage: The following example shows how to arm a one-shot time event from a state machine of an active object:
QState Philo_eating(Philo * const me, QEvt const * const e) {
QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
QTimeEvt_armX(&me->timeEvt, EAT_TIME, 0U); /* one shot */
status = Q_HANDLED();
break;
}
case Q_EXIT_SIG: {
TableEvt *pe;
QTimeEvt_disarm(&me->timeEvt);
pe = Q_NEW(TableEvt, DONE_SIG);
pe->philNum = me->num;
QF_PUBLISH((QEvt *)pe, me);
status = Q_HANDLED();
break;
}
case TIMEOUT_SIG: {
status = Q_TRAN(&Philosopher_thinking);
break;
}
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}

Precondition: the host AO must be valid, time evnet must be disarmed, number of clock ticks cannot be zero, and the signal must be valid.

Definition at line 296 of file qf_time.c.

◆ QTimeEvt_rearm()

bool QTimeEvt_rearm	(	QTimeEvt *const	me,
		QTimeEvtCtr const	nTicks
	)

Rearm a time event.

Description: Rearms a time event with a new number of clock ticks. This function can be used to adjust the current period of a periodic time event or to prevent a one-shot time event from expiring (e.g., a watchdog time event). Rearming a periodic timer leaves the interval unchanged and is a convenient method to adjust the phasing of a periodic time event.

Parameters

[in,out]	me	pointer (see Object Orientation)
[in]	nTicks	number of clock ticks (at the associated rate) to rearm the time event with.

Returns: 'true' if the time event was running as it was re-armed. The 'false' return means that the time event was not truly rearmed because it was not running. The 'false' return is only possible for one-shot time events that have been automatically disarmed upon expiration. In this case the 'false' return means that the time event has already been posted or published and should be expected in the active object's state machine.

Precondition: AO must be valid, tick rate must be in range, nTicks must not be zero, and the signal of this time event must be valid

Definition at line 431 of file qf_time.c.

◆ QTimeEvt_disarm()

bool QTimeEvt_disarm ( QTimeEvt *const me )

Disarm a time event.

Description: Disarm the time event so it can be safely reused.

Parameters

[in,out] me pointer (see Object Orientation)

Returns: 'true' if the time event was truly disarmed, that is, it was running. The return of 'false' means that the time event was not truly disarmed, because it was not running. The 'false' return is only possible for one- shot time events that have been automatically disarmed upon expiration. In this case the 'false' return means that the time event has already been posted or published and should be expected in the active object's state machine.

Note: there is no harm in disarming an already disarmed time event

Definition at line 371 of file qf_time.c.

◆ QTimeEvt_wasDisarmed()

bool QTimeEvt_wasDisarmed ( QTimeEvt *const me )

Check the "was disarmed" status of a time event.

Description: Useful for checking whether a one-shot time event was disarmed in the QTimeEvt_disarm() operation.

Parameters

[in,out] me pointer (see Object Orientation)

Returns: 'true' if the time event was truly disarmed in the last QTimeEvt_disarm() operation. The 'false' return means that the time event was not truly disarmed, because it was not running at that time. The 'false' return is only possible for one-shot time events that have been automatically disarmed upon expiration. In this case the 'false' return means that the time event has already been posted or published and should be expected in the active object's event queue.

Note: This function has a side effect of setting the "was disarmed" status, which means that the second and subsequent times this function is called the function will return 'true'.

Definition at line 513 of file qf_time.c.

◆ QTimeEvt_ctr()

QTimeEvtCtr QTimeEvt_ctr ( QTimeEvt const *const me )

Get the current value of the down-counter of a time event.

Description: Useful for checking how many clock ticks (at the tick rate associated with the time event) remain until the time event expires.

Parameters

[in,out] me pointer (see Object Orientation)

Returns: For an armed time event, the function returns the current value of the down-counter of the given time event. If the time event is not armed, the function returns 0.

Note: The function is thread-safe.

Definition at line 535 of file qf_time.c.

◆ QF_init()

void QF_init ( void )

QF initialization.

Description: Initializes QF and must be called exactly once before any other QF function. Typically, QF_init() is called from main() even before initializing the Board Support Package (BSP).

Note: QF_init() clears the internal QF variables, so that the framework can start correctly even if the startup code fails to clear the uninitialized data (as is required by the C Standard).

Definition at line 55 of file qutest.c.

◆ QF_psInit()

void QF_psInit	(	QSubscrList *const	subscrSto,
		enum_t const	maxSignal
	)

Publish-subscribe initialization.

Description: This function initializes the publish-subscribe facilities of QF and must be called exactly once before any subscriptions/publications occur in the application.

Parameters

[in]	subscrSto	pointer to the array of subscriber lists
[in]	maxSignal	the dimension of the subscriber array and at the same time the maximum signal that can be published or subscribed.

The array of subscriber-lists is indexed by signals and provides a mapping between the signals and subscriber-lists. The subscriber-lists are bitmasks of type QSubscrList, each bit in the bit mask corresponding to the unique priority of an active object. The size of the QSubscrList bit mask depends on the value of the QF_MAX_ACTIVE macro.

Note: The publish-subscribe facilities are optional, meaning that you might choose not to use publish-subscribe. In that case calling QF_psInit() and using up memory for the subscriber-lists is unnecessary.

See also: QSubscrList

Usage: The following example shows the typical initialization sequence of QF:
#include "qpc.h"
Q_DEFINE_THIS_FILE
int main(void) {
static QEvt const *l_tableQueueSto[N_PHILO];
static QEvt const *l_philoQueueSto[N_PHILO][N_PHILO];
static QSubscrList l_subscrSto[MAX_PUB_SIG];
/* storage for event pools... */
static QF_MPOOL_EL(TableEvt) l_smlPoolSto[2*N_PHILO]; /* small pool */
uint8_t n;
Philo_ctor(); /* instantiate all Philosopher active objects */
Table_ctor(); /* instantiate the Table active object */
QF_init(); /* initialize the framework and the underlying RT kernel */
BSP_init(); /* initialize the BSP */
/* send object dictionaries for event pools... */
QS_OBJ_DICTIONARY(l_smlPoolSto);
/* init publish-subscribe... */
QF_psInit(l_subscrSto, Q_DIM(l_subscrSto));
/* initialize event pools... */
QF_poolInit(l_smlPoolSto, sizeof(l_smlPoolSto), sizeof(l_smlPoolSto[0]));
/* start the active objects... */
for (n = 0; n < N_PHILO; ++n) {
QACTIVE_START(AO_Philo[n], (uint8_t)(n + 1),
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]),
(void *)0, 0U, (QEvt *)0);
}
QACTIVE_START(AO_Table, (uint8_t)(N_PHILO + 1),
l_tableQueueSto, Q_DIM(l_tableQueueSto),
(void *)0, 0U, (QEvt *)0);
return QF_run(); /* run the QF application, QF_run() does not return */
}

Definition at line 86 of file qf_ps.c.

◆ QF_poolInit()

void QF_poolInit	(	void *const	poolSto,
		uint_fast32_t const	poolSize,
		uint_fast16_t const	evtSize
	)

Event pool initialization for dynamic allocation of events.

Description: This function initializes one event pool at a time and must be called exactly once for each event pool before the pool can be used.

Parameters

[in]	poolSto	pointer to the storage for the event pool
[in]	poolSize	size of the storage for the pool in bytes
[in]	evtSize	the block-size of the pool in bytes, which determines the maximum size of events that can be allocated from the pool.

Attention: You might initialize many event pools by making many consecutive calls to the QF_poolInit() function. However, for the simplicity of the internal implementation, you must initialize event pools in the ascending order of the event size.

Many RTOSes provide fixed block-size heaps, a.k.a. memory pools that can be adapted for QF event pools. In case such support is missing, QF provides a native QF event pool implementation. The macro QF_EPOOL_TYPE_ determines the type of event pool used by a particular QF port. See structure QMPool for more information.

Note: The actual number of events available in the pool might be actually less than (poolSize / evtSize) due to the internal alignment of the blocks that the pool might perform. You can always check the capacity of the pool by calling QF_getPoolMin().; The dynamic allocation of events is optional, meaning that you might choose not to use dynamic events. In that case calling QF_poolInit() and using up memory for the memory blocks is unnecessary.

See also: QF initialization example for QF_init()

Precondition: cannot exceed the number of available memory pools; please initialize event pools in ascending order of evtSize:

Definition at line 112 of file qf_dyn.c.

◆ QF_poolGetMaxBlockSize()

uint_fast16_t QF_poolGetMaxBlockSize ( void )

Obtain the block size of any registered event pools.

Description: Obtain the block size of any registered event pools

Definition at line 337 of file qf_dyn.c.

◆ QF_run()

int_t QF_run ( void )

Transfers control to QF to run the application.

Description: QF_run() is typically called from main() after you initialize the QF and start at least one active object with QACTIVE_START().

Returns: In QV, the QF_run() function does not return.

Definition at line 70 of file qutest.c.

◆ QF_stop()

void QF_stop ( void )

Function invoked by the application layer to stop the QF application and return control to the OS/Kernel.

Description: This function stops the QF application. After calling this function, QF attempts to gracefully stop the application. This graceful shutdown might take some time to complete. The typical use of this function is for terminating the QF application to return back to the operating system or for handling fatal errors that require shutting down (and possibly re-setting) the system.

See also: QF_onCleanup()

Definition at line 66 of file qutest.c.

◆ QF_onStartup()

void QF_onStartup ( void )

Startup QF callback.

Description: The timeline for calling QF_onStartup() depends on the particular QF port. In most cases, QF_onStartup() is called from QF_run(), right before starting any multitasking kernel or the background loop.

◆ QF_onCleanup()

void QF_onCleanup ( void )

Cleanup QF callback.

Description: QF_onCleanup() is called in some QF ports before QF returns to the underlying operating system or RTOS.

This function is strongly platform-specific and is not implemented in the QF, but either in the QF port or in the Board Support Package (BSP) for the given application. Some QF ports might not require implementing QF_onCleanup() at all, because many embedded applications don't have anything to exit to.

See also: QF_stop()

◆ QF_publish_()

void QF_publish_	(	QEvt const *const	e,
		void const *const	sender
	)

Publish event to the framework.

Description: 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.

Attention: this function should be called only via the macro QF_PUBLISH()

Precondition: the published signal must be within the configured range

Definition at line 122 of file qf_ps.c.

◆ QF_tickX_()

void QF_tickX_	(	uint_fast8_t const	tickRate,
		void const *const	sender
	)

Processes all armed time events at every clock tick.

Description: This function must be called periodically from a time-tick ISR or from a task so that QF can manage the timeout events assigned to the given system clock tick rate.

Parameters

[in] tickRate system clock tick rate serviced in this call [1..15].

Note: this function should be called only via the macro QF_TICK_X(); the calls to QF_tickX_() with different tickRate parameter can preempt each other. For example, higher clock tick rates might be serviced from interrupts while others from tasks (active objects).

See also: QTimeEvt.

Definition at line 78 of file qf_time.c.

◆ QF_noTimeEvtsActiveX()

bool QF_noTimeEvtsActiveX ( uint_fast8_t const tickRate )

Returns 'true' if there are no armed time events at a given tick rate.

Description: Find out if any time events are armed at the given clock tick rate.

Parameters

[in] tickRate system clock tick rate to find out about.

Returns: 'true' if no time events are armed at the given tick rate and 'false' otherwise.

Note: This function should be called in critical section.

Definition at line 204 of file qf_time.c.

◆ QF_add_()

void QF_add_ ( QActive *const a )

Register an active object to be managed by the framework.

Description: 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 by the QP ports.

Parameters

[in] a pointer to the active object to add to the framework.

Note: The priority of the active object a should be set before calling this function.

See also: QF_remove_()

Precondition: the priority of the active object must not be zero and cannot exceed the maximum QF_MAX_ACTIVE. Also, the priority of the active object must not be already in use. QF requires each active object to have a unique priority.

Definition at line 69 of file qf_act.c.

◆ QF_remove_()

void QF_remove_ ( QActive *const a )

Remove the active object from the framework.

Description: This function removes a given active object from the active objects managed by the QF framework. It should not be called by the application directly, only by the QP ports.

Parameters

[in] a pointer to the active object to remove from the framework.

Note: The active object that is removed from the framework can no longer participate in the publish-subscribe event exchange.

See also: QF_add_()

Precondition: the priority of the active object must not be zero and cannot exceed the maximum QF_MAX_ACTIVE. Also, the priority of the active object must be already registered with the framework.

Definition at line 102 of file qf_act.c.

◆ QF_getPoolMin()

uint_fast16_t QF_getPoolMin ( uint_fast8_t const poolId )

Obtain the minimum of free entries of the given event pool.

Description: This function obtains the minimum number of free blocks in the given event pool since this pool has been initialized by a call to QF_poolInit().

Parameters

[in] poolId event pool ID in the range 1..QF_maxPool_, where QF_maxPool_ is the number of event pools initialized with the function QF_poolInit().

Returns: the minimum number of unused blocks in the given event pool.

Precondition: the poolId must be in range

Definition at line 290 of file qf_mem.c.

◆ QF_getQueueMin()

uint_fast16_t QF_getQueueMin ( uint_fast8_t const prio )

This function returns the minimum of free entries of the given event queue.

Description: 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.

Note: This function is available only when the native QF event queue implementation is used. Requesting the queue minimum of an unused priority level raises an assertion in the QF. (A priority level becomes used in QF after the call to the QF_add_() function.)

Parameters

[in] prio Priority of the active object, whose queue is queried

Returns: the minimum of free ever present in the given event queue of an active object with priority prio, since the active object was started.

Definition at line 396 of file qf_actq.c.

◆ QF_newX_()

QEvt* QF_newX_	(	uint_fast16_t const	evtSize,
		uint_fast16_t const	margin,
		enum_t const	sig
	)

Internal QF implementation of creating new dynamic event.

Description: Allocates an event dynamically from one of the QF event pools.

Parameters

[in]	evtSize	the size (in bytes) of the event to allocate
[in]	margin	the number of un-allocated events still available in a given event pool after the allocation completes. The special value QF_NO_MARGIN means that this function will assert if allocation fails.
[in]	sig	the signal to be assigned to the allocated event

Returns: pointer to the newly allocated event. This pointer can be NULL only if margin!=0 and the event cannot be allocated with the specified margin still available in the given pool.

Note: The internal QF function QF_newX_() raises an assertion when the margin parameter is QF_NO_MARGIN and allocation of the event turns out to be impossible due to event pool depletion, or incorrect (too big) size of the requested event.; The application code should not call this function directly. The only allowed use is thorough the macros Q_NEW() or Q_NEW_X().

Definition at line 163 of file qf_dyn.c.

◆ QF_newRef_()

QEvt const* QF_newRef_	(	QEvt const *const	e,
		void const *const	evtRef
	)

Internal QF implementation of creating new event reference.

Description: Creates and returns a new reference to the current event e

Parameters

[in]	e	pointer to the current event
[in]	evtRef	the event reference

Returns: the newly created reference to the event e

Note: The application code should not call this function directly. The only allowed use is thorough the macro Q_NEW_REF().

Precondition: the event must be dynamic and the provided event reference must not be already in use

Definition at line 285 of file qf_dyn.c.

◆ QF_deleteRef_()

void QF_deleteRef_ ( void const *const evtRef )

Internal QF implementation of deleting event reference.

Description: Deletes an existing reference to the event e

Parameters

[in] evtRef the event reference

Note: The application code should not call this function directly. The only allowed use is thorough the macro Q_DELETE_REF().

Definition at line 319 of file qf_dyn.c.

◆ QF_gc()

void QF_gc ( QEvt const *const e )

Recycle a dynamic event.

Description: This function implements a simple garbage collector for the dynamic events. Only dynamic events are candidates for recycling. (A dynamic event is one that is allocated from an event pool, which is determined as non-zero e->poolId_ attribute.) Next, the function decrements the reference counter of the event (e->refCtr_), and recycles the event only if the counter drops to zero (meaning that no more references are outstanding for this event). The dynamic event is recycled by returning it to the pool from which it was originally allocated.

Parameters

[in] e pointer to the event to recycle

Note: QF invokes the garbage collector at all appropriate contexts, when an event can become garbage (automatic garbage collection), so the application code should have no need to call QF_gc() directly. The QF_gc() function is exposed only for special cases when your application sends dynamic events to the "raw" thread-safe queues (see QEQueue). Such queues are processed outside of QF and the automatic garbage collection is NOT performed for these events. In this case you need to call QF_gc() explicitly.

Definition at line 229 of file qf_dyn.c.

◆ QF_bzero()

void QF_bzero	(	void *const	start,
		uint_fast16_t	len
	)

Clear a specified region of memory to zero.

Description: Clears a memory buffer by writing zeros byte-by-byte.

Parameters

[in]	start	pointer to the beginning of a memory buffer.
[in]	len	length of the memory buffer to clear (in bytes)

Note: The main application of this function is clearing the internal QF variables upon startup. This is done to avoid problems with non-standard startup code provided with some compilers and toolsets (e.g., TI DSPs or Microchip MPLAB), which does not zero the uninitialized variables, as required by the ANSI C standard.

Definition at line 144 of file qf_act.c.

◆ QTicker_ctor()

void QTicker_ctor	(	QTicker *const	me,
		uint8_t	tickRate
	)

Constructor of the QTicker Active Object class.

Definition at line 437 of file qf_actq.c.

Variable Documentation

◆ QF_active_

QActive* QF_active_[QF_MAX_ACTIVE+1]

array of registered active objects

Note: Not to be used by Clients directly, only in ports of QF

Definition at line 53 of file qf_act.c.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Data Structure Documentation

◆ QActive

◆ QTimeEvt

Macro Definition Documentation

◆ QF_EVENT_SIZ_SIZE

◆ QF_MAX_EPOOL

◆ QF_MAX_TICK_RATE

◆ QF_TIMEEVT_CTR_SIZE

◆ QACTIVE_START

◆ QACTIVE_POST

◆ QACTIVE_POST_X

◆ QACTIVE_POST_LIFO

◆ QF_PUBLISH

◆ QF_TICK_X

◆ QF_NO_MARGIN

◆ QF_TICK

◆ Q_NEW

◆ Q_NEW_X

◆ Q_NEW_REF

◆ Q_DELETE_REF

◆ QF_CRIT_EXIT_NOP

◆ QF_getVersion

Typedef Documentation

◆ QEvtSize

◆ QMActive

◆ QMActiveVtbl

◆ QTimeEvtCtr

◆ QSubscrList

◆ QTicker

Function Documentation

◆ QActive_ctor()

◆ QActive_subscribe()

◆ QActive_unsubscribe()

◆ QActive_unsubscribeAll()

◆ QActive_defer()

◆ QActive_recall()

◆ QActive_flushDeferred()

◆ QActive_setAttr()

◆ QMActive_ctor()

◆ QTimeEvt_ctorX()

◆ QTimeEvt_armX()

◆ QTimeEvt_rearm()

◆ QTimeEvt_disarm()

◆ QTimeEvt_wasDisarmed()

◆ QTimeEvt_ctr()

◆ QF_init()

◆ QF_psInit()

◆ QF_poolInit()

◆ QF_poolGetMaxBlockSize()

◆ QF_run()

◆ QF_stop()

◆ QF_onStartup()

◆ QF_onCleanup()

◆ QF_publish_()

◆ QF_tickX_()

◆ QF_noTimeEvtsActiveX()

◆ QF_add_()

◆ QF_remove_()

◆ QF_getPoolMin()

◆ QF_getQueueMin()

◆ QF_newX_()

◆ QF_newRef_()

◆ QF_deleteRef_()

◆ QF_gc()

◆ QF_bzero()

◆ QTicker_ctor()

Variable Documentation

◆ QF_active_