QP/C
7.4.0-rc.3
Real-Time Embedded Framework
Native QF Event Queue. More...
#include "qequeue.h"
Public Member Functions | |
| void | QEQueue_init (QEQueue *const me, struct QEvt const **const qSto, uint_fast16_t const qLen) |
| Initialize the native QF event queue. | |
| bool | QEQueue_post (QEQueue *const me, struct QEvt const *const e, uint_fast16_t const margin, uint_fast8_t const qsId) |
| Post an event to the "raw" thread-safe event queue (FIFO) | |
| void | QEQueue_postLIFO (QEQueue *const me, struct QEvt const *const e, uint_fast8_t const qsId) |
| Post an event to the "raw" thread-safe event queue (LIFO) | |
| struct QEvt const * | QEQueue_get (QEQueue *const me, uint_fast8_t const qsId) |
| Obtain an event from the "raw" thread-safe queue. | |
Static Public Member Functions | |
| static QEQueueCtr | QEQueue_getNFree (QEQueue const *const me) |
| Obtain the number of free entries still available in the queue. | |
| static QEQueueCtr | QEQueue_getNMin (QEQueue const *const me) |
| Obtain the minimum number of free entries ever in the queue (a.k.a. "low-watermark") | |
| static bool | QEQueue_isEmpty (QEQueue const *const me) |
| Find out if the queue is empty. | |
Private Attributes | |
| struct QEvt const *volatile | frontEvt |
| Pointer to event at the front of the queue. | |
| struct QEvt 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 volatile | head |
| Offset to where next event will be inserted into the buffer. | |
| QEQueueCtr volatile | tail |
| Offset of where next event will be extracted from the buffer. | |
| QEQueueCtr volatile | nFree |
| Number of free events in the ring buffer. | |
| QEQueueCtr | nMin |
| Minimum number of free events ever in the ring buffer. | |
Native QF Event Queue.
This class 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 QACTIVE_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 might need to block the active object task when the event queue is empty and might need to unblock it when events are posted to the queue. The interface for the native active object event queue consists of the following functions: QActive_post(), QActive_postLIFO(), and QActive_get_(). Additionally the function QEQueue_init() is used to initialize the queue.
The other set of functions, uses QEQueue 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_post(), QEQueue_postLIFO(), and QEQueue_get(). Additionally the function QEQueue_init() is used to initialize the queue.
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.
Initialize the native QF event queue.
Initialize the event queue by giving it the storage for the ring buffer.
| bool QEQueue_post | ( | QEQueue *const | me, |
| struct QEvt const *const | e, | ||
| uint_fast16_t const | margin, | ||
| uint_fast8_t const | qsId ) |
Post an event to the "raw" thread-safe event queue (FIFO)
Post an event to the "raw" thread-safe event queue using the First-In-First-Out (FIFO) order.
| [in,out] | me | current instance pointer (see oop) |
| [in] | e | pointer to the event to be posted to the queue |
| [in] | margin | number of required free slots in the queue after posting the event. The special value QF_NO_MARGIN means that this function will assert if posting |
| [in] | qsId | QS-id of this state machine (for QS local filter) |
qf_qeq:200margin parameter is special and denotes situation when the post() operation is assumed to succeed (event delivery guarantee). An assertion fires, when the event cannot be delivered in this case. Post an event to the "raw" thread-safe event queue (LIFO)
Post an event to the "raw" thread-safe event queue using the Last-In-First-Out (LIFO) order.
| [in,out] | me | current instance pointer (see oop) |
| [in] | e | pointer to the event to be posted to the queue |
| [in] | qsId | QS-id of this state machine (for QS local filter) |
qf_qeq:300Obtain an event from the "raw" thread-safe queue.
Retrieves an event from the front of the "raw" thread-safe queue and returns a pointer to this event to the caller.
| [in,out] | me | current instance pointer (see oop) |
| [in] | qsId | QS-id of this state machine (for QS local filter) |
|
inlinestatic |
Obtain 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.
| [in] | me | current instance pointer (see oop) |
|
inlinestatic |
Obtain 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.
| [in] | me | current instance pointer (see oop) |
|
inlinestatic |
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.
| [in,out] | me | current instance pointer (see oop) |
|
private |
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 when frontEvt is NULL.
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |