QP/C  7.0.0
Real-Time Embedded Framework
qequeue.h File Reference

QP natvie, platform-independent, thread-safe event queue interface. More...

Go to the source code of this file.

Data Structures

struct  QEQueue
 

Typedefs

typedef uint8_t QEQueueCtr
 

Functions

void QEQueue_init (QEQueue *const me, QEvt const **const qSto, uint_fast16_t const qLen)
 
bool QEQueue_post (QEQueue *const me, QEvt const *const e, uint_fast16_t const margin, uint_fast8_t const qs_id)
 
void QEQueue_postLIFO (QEQueue *const me, QEvt const *const e, uint_fast8_t const qs_id)
 
QEvt const * QEQueue_get (QEQueue *const me, uint_fast8_t const qs_id)
 
static QEQueueCtr QEQueue_getNFree (QEQueue *const me)
 
static QEQueueCtr QEQueue_getNMin (QEQueue *const me)
 
static bool QEQueue_isEmpty (QEQueue *const me)
 

Detailed Description

Date
Last updated on: 2021-12-23
Version
Last updated for: Version 7.0.0, 2022-04-30

This header file must be included in all QF ports that use native QF event queue for active objects. Also, this file needs to be included in the QP/C library when the application uses QActive_defer()/ QActive_recall(). Finally, this file is also needed when the "raw" thread-safe queues are used for communication between active objects and non-framework entities, such as ISRs, device drivers, or legacy code.

Definition in file qequeue.h.

Typedef Documentation

◆ QEQueueCtr

typedef uint8_t QEQueueCtr

The data type to store the ring-buffer counters based on the macro #QF_EQUEUE_CTR_SIZE.

The dynamic range of this data type determines the maximum length of the ring buffer managed by the native QF event queue.

Definition at line 63 of file qequeue.h.

Function Documentation

◆ QEQueue_init()

void QEQueue_init ( QEQueue *const  me,
QEvt const **const  qSto,
uint_fast16_t const  qLen 
)

Initialize the native QF event queue

◆ QEQueue_post()

bool QEQueue_post ( QEQueue *const  me,
QEvt const *const  e,
uint_fast16_t const  margin,
uint_fast8_t const  qs_id 
)

Post an event to the "raw" thread-safe event queue (FIFO).

◆ QEQueue_postLIFO()

void QEQueue_postLIFO ( QEQueue *const  me,
QEvt const *const  e,
uint_fast8_t const  qs_id 
)

Post an event to the "raw" thread-safe event queue (LIFO).

◆ QEQueue_get()

QEvt const * QEQueue_get ( QEQueue *const  me,
uint_fast8_t const  qs_id 
)

Obtain an event from the "raw" thread-safe queue.

◆ QEQueue_getNFree()

static QEQueueCtr QEQueue_getNFree ( QEQueue *const  me)
inlinestatic

"raw" thread-safe QF event queue operation for obtaining the number of free entries still available in the queue.

This operation needs to be used with caution because the number of free entries can change unexpectedly. The main intent for using this operation is in conjunction with event deferral. In this case the queue is accessed only from a single thread (by a single AO), so the number of free entries cannot change unexpectedly.

Parameters
[in]mepointer (see oop)
Returns
the current number of free slots in the queue.

Definition at line 185 of file qequeue.h.

◆ QEQueue_getNMin()

static QEQueueCtr QEQueue_getNMin ( QEQueue *const  me)
inlinestatic

"raw" thread-safe QF event queue operation for obtaining the minimum number of free entries ever in the queue (a.k.a. "low-watermark").

This operation needs to be used with caution because the "low-watermark" can change unexpectedly. The main intent for using this operation is to get an idea of queue usage to size the queue adequately.

Parameters
[in]mepointer (see oop)
Returns
the minimum number of free entries ever in the queue since init.

Definition at line 200 of file qequeue.h.

◆ QEQueue_isEmpty()

static bool QEQueue_isEmpty ( QEQueue *const  me)
inlinestatic

"raw" thread-safe QF event queue operation to find out if the queue is empty.

This operation needs to be used with caution because the queue status can change unexpectedly. The main intent for using this operation is in conjunction with event deferral. In this case the queue is accessed only from a single thread (by a single AO), so no other entity can post events to the queue.

Parameters
[in]me_pointer (see oop)
Returns
'true' if the queue is current empty and 'false' otherwise.

Definition at line 217 of file qequeue.h.