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]

me

pointer (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]

me

pointer (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.