qequeue.h File Reference

platform-independent event queue interface. More...

Go to the source code of this file.

Data Structures
struct	QEQueue
	Native QF Event Queue. More...
Defines
#define	QF_EQUEUE_CTR_SIZE   1
	The size (in bytes) of the ring-buffer counters used in the native QF event queue implementation. Valid values: 1, 2, or 4; default 1.
#define	QEQueue_getNFree(me_)   ((me_)->nFree)
	"raw" thread-safe QF event queue operation for obtaining the number of free entries still available in the queue.
Typedefs
typedef uint8_t	QEQueueCtr
	The data type to store the ring-buffer counters based on the macro QF_EQUEUE_CTR_SIZE.
Functions
void	QEQueue_init (QEQueue *me, QEvent const *qSto[], QEQueueCtr qLen)
	Initializes the native QF event queue.
void	QEQueue_postFIFO (QEQueue *me, QEvent const *e)
	"raw" thread-safe QF event queue implementation for the First-In-First-Out (FIFO) event posting. You can call this function from any task context or ISR context. Please note that this function uses internally a critical section.
void	QEQueue_postLIFO (QEQueue *me, QEvent const *e)
	"raw" thread-safe QF event queue implementation for the Last-In-First-Out (LIFO) event posting.
QEvent const *	QEQueue_get (QEQueue *me)
	"raw" thread-safe QF event queue implementation for the event get operation.

---

Detailed Description

platform-independent event queue interface.

This header file must be included in all QF ports that use native QF event queue implementation. Also, this file is 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.

---

Define Documentation

#define QEQueue_getNFree

(

me_

)

((me_)->nFree)

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

Note:

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.

See also:

QActive_defer(), QActive_recall()

Definition at line 222 of file qequeue.h.

#define QF_EQUEUE_CTR_SIZE   1

The size (in bytes) of the ring-buffer counters used in the native QF event queue implementation. Valid values: 1, 2, or 4; default 1.

This macro can be defined in the QF port file (qf_port.h) to configure the QEQueueCtr type. Here the macro is not defined so the default of 1 byte is chosen.

Definition at line 53 of file qequeue.h.

---

Typedef Documentation

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

QEvent const* QEQueue_get

(

QEQueue *

me

)

"raw" thread-safe QF event queue implementation for the event get operation.

If the queue has one or more events, the function returns the event at the front of the queue, otherwise it returns NULL. You can call this function from any task context or ISR context. Please note that this function uses internally a critical section.

See also:

QEQueue_postFIFO(), QEQueue_postLIFO()

Definition at line 41 of file qeq_get.c.

References QEQueue::end, QEQueue::frontEvt, QEQueue::nFree, QF_EVT_POOL_ID_, QF_EVT_REF_CTR_, QF_PTR_AT_, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_EQC_, QS_eqObj_, QS_OBJ_, QS_QF_EQUEUE_GET, QS_QF_EQUEUE_GET_LAST, QS_TIME_, QS_U8_, QEQueue::ring, QEvent::sig, and QEQueue::tail.

Referenced by QActive_recall().

void QEQueue_init	(	QEQueue *	me,
		QEvent const *	qSto[],
		QEQueueCtr	qLen
	)

Initializes the native QF event queue.

The parameters are as follows: me points to the QEvent struct to be initialized, qSto[] is the ring buffer storage, qLen is the length of the ring buffer in the units of event-pointers.

Note:

The actual capacity of the queue is qLen + 1, because of the extra location fornEvt.

Definition at line 38 of file qeq_init.c.

References QEQueue::end, QEQueue::frontEvt, QEQueue::head, QEQueue::nFree, QEQueue::nMin, QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_EQC_, QS_eqObj_, QS_OBJ_, QS_QF_EQUEUE_INIT, QEQueue::ring, and QEQueue::tail.

Referenced by QActive_start().

void QEQueue_postFIFO	(	QEQueue *	me,
		QEvent const *	e
	)

"raw" thread-safe QF event queue implementation for the First-In-First-Out (FIFO) event posting. You can call this function from any task context or ISR context. Please note that this function uses internally a critical section.

Note:

The function raises an assertion if the native QF queue becomes full and cannot accept the event.

See also:

QEQueue_postLIFO(), QEQueue_get()

Definition at line 41 of file qeq_fifo.c.

References Q_ASSERT, QF_EVT_POOL_ID_, QF_EVT_REF_CTR_, QF_EVT_REF_CTR_INC_, QF_PTR_AT_, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_EQC_, QS_eqObj_, QS_OBJ_, QS_QF_EQUEUE_POST_FIFO, QS_TIME_, and QS_U8_.

Referenced by QActive_defer().

void QEQueue_postLIFO	(	QEQueue *	me,
		QEvent const *	e
	)

"raw" thread-safe QF event queue implementation for the Last-In-First-Out (LIFO) event posting.

Note:

The LIFO policy should be used only with great caution because it alters order of events in the queue.

The function raises an assertion if the native QF queue becomes full and cannot accept the event. You can call this function from any task context or ISR context. Please note that this function uses internally a critical section.

See also:

QEQueue_postFIFO(), QEQueue_get()

Definition at line 41 of file qeq_lifo.c.

References Q_ASSERT, QF_EVT_POOL_ID_, QF_EVT_REF_CTR_, QF_EVT_REF_CTR_INC_, QF_PTR_AT_, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_EQC_, QS_eqObj_, QS_OBJ_, QS_QF_EQUEUE_POST_LIFO, QS_TIME_, and QS_U8_.