QEQueue Struct Reference

Native QF Event Queue. More...

#include <qequeue.h>

Data Fields
QEvent const *	frontEvt
	pointer to event at the front of the queue
QEvent const **	ring
	pointer to the start of the ring buffer
QEQueueCtr	end
	offset of the end of the ring buffer from the start of the buffer
QEQueueCtr	head
	offset to where next event will be inserted into the buffer
QEQueueCtr	tail
	offset of where next event will be extracted from the buffer
QEQueueCtr	nFree
	number of free events in the ring buffer
QEQueueCtr	nMin
	minimum number of free events ever in the ring buffer.

---

Detailed Description

Native QF Event Queue.

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.

See also:

::QEQueueTag for the description of the data members

Definition at line 116 of file qequeue.h.

---

Field Documentation

QEvent const* QEQueue::frontEvt

pointer to event at the front of the queue

All incoming and outgoing events pass through the frontEvt location. When the queue is empty (which is most of the time), the extra frontEvt location allows to bypass the ring buffer altogether, greatly optimizing the performance of the queue. Only bursts of events engage the ring buffer.

The additional role of this attribute is to indicate the empty status of the queue. The queue is empty if the frontEvt location is NULL.

Definition at line 128 of file qequeue.h.

Referenced by QEQueue_get(), and QEQueue_init().

QEQueueCtr QEQueue::nMin

minimum number of free events ever in the ring buffer.

Note:

this attribute remembers the low-watermark of the ring buffer, which provides a valuable information for sizing event queues.

See also:

QF_getQueueMargin().

Definition at line 157 of file qequeue.h.

Referenced by QEQueue_init().

---

The documentation for this struct was generated from the following file:

• qequeue.h