QP/C  5.8.2
qf_actq.c File Reference

QActive native queue operations (based on QEQueue) More...

#include "qf_port.h"
#include "qf_pkg.h"
#include "qassert.h"
#include "qs_port.h"

Go to the source code of this file.

Macros

#define QP_IMPL   /* this is QP implementation */
 

Functions

bool QActive_post_ (QActive *const me, QEvt const *const e, uint_fast16_t const margin, void const *const sender)
 Implementation of the active object post (FIFO) operation. More...
 
void QActive_postLIFO_ (QActive *const me, QEvt const *const e)
 Implementation of the active object post LIFO operation. More...
 
QEvt const * QActive_get_ (QActive *const me)
 Get an event from the event queue of an active object. 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...
 
static void QTicker_init_ (QHsm *const me, QEvt const *const e)
 
static void QTicker_dispatch_ (QHsm *const me, QEvt const *const e)
 
static bool QTicker_post_ (QActive *const me, QEvt const *const e, uint_fast16_t const margin, void const *const sender)
 virtual function to asynchronously post (FIFO) an event to an AO
 
static void QTicker_postLIFO_ (QActive *const me, QEvt const *const e)
 
void QTicker_ctor (QTicker *const me, uint8_t tickRate)
 "constructor" of QTicker More...
 

Detailed Description

QActive native queue operations (based on QEQueue)

Note
this source file is only included in the QF library when the native QF active object queue is used (instead of a message queue of an RTOS).

Definition in file qf_actq.c.

Function Documentation

◆ QActive_get_()

QEvt const* QActive_get_ ( QActive *const  me)

Get an event from the event queue of an active object.

Description
The behavior of this function depends on the kernel/OS 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
[in,out]mepointer (see Object Orientation)
Returns
a pointer to the received event. The returned pointer is always valid (can't be NULL).

Definition at line 262 of file qf_actq.c.

◆ QActive_post_()

bool QActive_post_ ( QActive *const  me,
QEvt const *const  e,
uint_fast16_t const  margin,
void const *const  sender 
)

Implementation of the active object post (FIFO) operation.

Description
Direct event posting is the simplest asynchronous communication method available in QF. The following example illustrates how the Philo active object posts directly the HUNGRY event to the Table active object.

The parameter margin specifies the minimum number of free slots in the queue that must be available for posting to succeed. The function returns 1 (success) if the posting succeeded (with the provided margin) and 0 (failure) when the posting fails.
Parameters
[in,out]mepointer (see Object Orientation)
[in]epointer to the event to be posted
[in]marginnumber of required free slots in the queue after posting the event.
Note
this function should be called only via the macro QACTIVE_POST() or QACTIVE_POST_X().
The zero value of the margin parameter is special and denotes situation when the post() operation is assumed to succeed (event delivery guarantee). An assertion fires, when the event cannot be delivered in this case.
Direct event posting should not be confused with direct event dispatching. In contrast to asynchronous event posting through event queues, direct event dispatching is synchronous. Direct event dispatching occurs when you call QMSM_DISPATCH().
This function is used internally by a QF port to extract events from the event queue of an active object. This function depends on the event queue implementation and is sometimes implemented in the QF port (file qf_port.c). Depending on the underlying OS or kernel, the function might block the calling thread when no events are available.
Usage
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;
}
See also
QActive_post_(), QActive_postLIFO()
Precondition
event pointer must be valid
Note
assert if event cannot be posted and dropping events is not acceptable

Definition at line 103 of file qf_actq.c.

◆ QActive_postLIFO_()

void QActive_postLIFO_ ( QActive *const  me,
QEvt const *const  e 
)

Implementation of the active object post LIFO operation.

Description
posts an event to the event queue of the active object me using the Last-In-First-Out (LIFO) policy.
Note
The LIFO policy should be used only for self-posting and with caution because it alters order of events in the queue.
Parameters
[in]mepointer (see Object Orientation)

Definition at line 198 of file qf_actq.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
QF_getQueueMin() 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]prioPriority 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 327 of file qf_actq.c.

◆ QTicker_ctor()

void QTicker_ctor ( QTicker *const  me,
uint8_t  tickRate 
)

"constructor" of QTicker

Constructor of the QTicker Active Object class.

Definition at line 358 of file qf_actq.c.