QEQueue Class Reference

Native QF Event Queue class. More...

#include <qequeue.h>

List of all members.

Public Member Functions
void	init (QEvent const *qSto[], QEQueueCtr qLen)
	Initializes the native QF event queue.
void	postFIFO (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	postLIFO (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.
QEvent const *	get (void)
	"raw" thread-safe QF event queue implementation for the Last-In-First-Out (LIFO) event posting.
QEQueueCtr	getNFree (void) const
	"raw" thread-safe QF event queue operation for obtaining the number of free entries still available in the queue.
Friends
class	QF
class	QActive

---

Detailed Description

Native QF Event Queue class.

This structure describes the native QF event queue, which can be used as the event queue for active objects, or as a simple "raw" event queue for thread-safe event passing among non-framework entities, such as ISRs, device drivers, or other third-party components.

The native QF event queue is configured by defining the macro QF_EQUEUE_TYPE as QEQueue in the specific QF port header file.

The QEQueue structure contains only data members for managing an event queue, but does not contain the storage for the queue buffer, which must be provided externally during the queue initialization.

The event queue can store only event pointers, not the whole events. The internal implementation uses the standard ring-buffer plus one external location that optimizes the queue operation for the most frequent case of empty queue.

The QEQueue structure is used with two sets of functions. One set is for the active object event queue, which needs to block the active object task when the event queue is empty and unblock it when events are posted to the queue. The interface for the native active object event queue consists of the following functions: QActive::postFIFO_(), QActive::postLIFO_(), and QActive::get_(). Additionally the function QEQueue_init() is used to initialize the queue.

The other set of functions, uses this structure as a simple "raw" event queue to pass events between entities other than active objects, such as ISRs. The "raw" event queue is not capable of blocking on the get() operation, but is still thread-safe because it uses QF critical section to protect its integrity. The interface for the "raw" thread-safe queue consists of the following functions: QEQueue::postFIFO(), QEQueue::postLIFO(), and QEQueue::get(). Additionally the function QEQueue::init() is used to initialize the queue.

Note:

Most event queue operations (both the active object queues and the "raw" queues) internally use the QF critical section. You should be careful not to invoke those operations from other critical sections when nesting of critical sections is not supported.

Definition at line 114 of file qequeue.h.

---

Member Function Documentation

QEvent const * QEQueue::get

(

void

)

"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 42 of file qeq_get.cpp.

References QS::eqObj_, EVT_POOL_ID, EVT_REF_CTR, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_EQC_, QS_OBJ_, QS_QF_EQUEUE_GET, QS_QF_EQUEUE_GET_LAST, QS_U8_, and QEvent::sig.

Referenced by QActive::recall().

QEQueueCtr QEQueue::getNFree

(

void

)

const [inline]

"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 209 of file qequeue.h.

void QEQueue::init	(	QEvent const *	qSto[],
		QEQueueCtr	qLen
	)

Initializes the native QF event queue.

The parameters are as follows: 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 39 of file qeq_init.cpp.

References QS::eqObj_, QS_BEGIN_, QS_CRIT_STAT_, QS_END_, QS_EQC_, QS_OBJ_, and QS_QF_EQUEUE_INIT.

void QEQueue::postFIFO

(

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 42 of file qeq_fifo.cpp.

References QS::eqObj_, EVT_INC_REF_CTR, EVT_POOL_ID, EVT_REF_CTR, Q_ASSERT, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_EQC_, QS_OBJ_, QS_QF_EQUEUE_POST_FIFO, and QS_U8_.

void QEQueue::postLIFO

(

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 42 of file qeq_lifo.cpp.

References QS::eqObj_, EVT_INC_REF_CTR, EVT_POOL_ID, EVT_REF_CTR, Q_ASSERT, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_EQC_, QS_OBJ_, QS_QF_EQUEUE_POST_LIFO, and QS_U8_.

---

The documentation for this class was generated from the following files:

• qequeue.h
• qeq_fifo.cpp
• qeq_get.cpp
• qeq_init.cpp
• qeq_lifo.cpp