QP/C++  6.9.3
Real-Time Embedded Framework
QEQueue Class Reference

#include <qequeue.hpp>

Collaboration diagram for QEQueue:
Collaboration graph

Public Member Functions

 QEQueue (void) noexcept
 public default constructor More...
 
void init (QEvt const *qSto[], std::uint_fast16_t const qLen) noexcept
 
bool post (QEvt const *const e, std::uint_fast16_t const margin, std::uint_fast8_t const qs_id) noexcept
 
void postLIFO (QEvt const *const e, std::uint_fast8_t const qs_id) noexcept
 
QEvt const * get (std::uint_fast8_t const qs_id) noexcept
 
QEQueueCtr getNFree (void) const noexcept
 
QEQueueCtr getNMin (void) const noexcept
 
bool isEmpty (void) const noexcept
 

Private Member Functions

 QEQueue (QEQueue const &)=delete
 disallow copying of QEQueue More...
 
QEQueueoperator= (QEQueue const &)=delete
 disallow assignment of QEQueue More...
 

Private Attributes

QEvt const *volatile m_frontEvt
 
QEvt const ** m_ring
 pointer to the start of the ring buffer More...
 
QEQueueCtr m_end
 offset of the end of the ring buffer from the start of the buffer More...
 
QEQueueCtr volatile m_head
 offset to where next event will be inserted into the buffer More...
 
QEQueueCtr volatile m_tail
 offset of where next event will be extracted from the buffer More...
 
QEQueueCtr volatile m_nFree
 number of free events in the ring buffer More...
 
QEQueueCtr m_nMin
 

Friends

class QF
 
class QActive
 
class QXThread
 
class QTicker
 
class QS
 

Detailed Description

Native QF Event Queue class

Description
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 QP::QEQueue in the specific QF port header file.

The QP::QEQueue class 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 QP::QEQueue class 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: QP::QMActive::post(), QP::QMActive::postLIFO(), and QP::QMActive::get_(). Additionally the function QP::QEQueue::init() is used to initialize the queue.

The other set of functions, uses this class 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: QP::QEQueue::post(), QP::QEQueue::postLIFO(), and QP::QEQueue::get(). Additionally the function QP::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 123 of file qequeue.hpp.

Constructor & Destructor Documentation

◆ QEQueue() [1/2]

QEQueue ( void  )
noexcept

public default constructor

Description
Default constructor

Definition at line 58 of file qf_qeq.cpp.

◆ QEQueue() [2/2]

QEQueue ( QEQueue const &  )
privatedelete

disallow copying of QEQueue

Member Function Documentation

◆ init()

void init ( QEvt const *  qSto[],
std::uint_fast16_t const  qLen 
)
noexcept

Initializes the native QF event queue

Description
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_.
Description
Initialize the event queue by giving it the storage for the ring buffer.
Parameters
[in]qStoan array of pointers to QP::QEvt to sereve as the ring buffer for the event queue
[in]qLenthe length of the qSto[] buffer (in QP::QEvt pointers)
Note
The actual capacity of the queue is qLen + 1, because of the extra location forntEvt.
This function is also used to initialize the event queues of active objects in the built-int QV, QK and QXK kernels, as well as other QP ports to OSes/RTOSes that do provide a suitable message queue.

Definition at line 84 of file qf_qeq.cpp.

◆ post()

bool post ( QEvt const *const  e,
std::uint_fast16_t const  margin,
std::uint_fast8_t const  qs_id 
)
noexcept

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

Description
The argument margin specifies the minimum number of free entries in the queue that must be available for posting to succeed. The function returns true (success) if the posting succeeded (with the provided margin) and false (failure) when the posting fails.
Note
The function raises an assertion if the margin is zero and the queue becomes full and cannot accept the event.
See also
QP::QEQueue::postLIFO(), QP::QEQueue::get()
Description
Post an event to the "raw" thread-safe event queue using the First-In-First-Out (FIFO) order.
Parameters
[in]epointer to the event to be posted to the queue
[in]marginnumber of required free slots in the queue after posting the event. The special value QP::QF_NO_MARGIN means that this function will assert if posting
[in]qs_idQS-id of this state machine (for QS local filter)
Note
The QP::QF_NO_MARGIN value of the margin argument 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.
Returns
'true' (success) when the posting succeeded with the provided margin and 'false' (failure) when the posting fails.
Note
This function can be called from any task context or ISR context.
See also
QP::QEQueue::postLIFO(), QP::QEQueue::get()
Precondition
event must be valid
Note
assert if event cannot be posted and dropping events is not acceptable

Definition at line 122 of file qf_qeq.cpp.

◆ postLIFO()

void postLIFO ( QEvt const *const  e,
std::uint_fast8_t const  qs_id 
)
noexcept

"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
QP::QEQueue::postLIFO(), QP::QEQueue::get()
Description
Post an event to the "raw" thread-safe event queue using the Last-In-First-Out (LIFO) order.
Parameters
[in]epointer to the event to be posted to the queue
[in]qs_idQS-id of this state machine (for QS local filter)
Attention
The LIFO policy should be used only with great caution, because it alters the order of events in the queue.
Note
This function can be called from any task context or ISR context.
This function is used for the "raw" thread-safe queues and not for the queues of active objects.
See also
QP::QEQueue::post(), QP::QEQueue::get(), QP::QActive::defer()
Precondition
the queue must be able to accept the event (cannot overflow)

Definition at line 221 of file qf_qeq.cpp.

◆ get()

QEvt const * get ( std::uint_fast8_t const  qs_id)
noexcept

"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
QP::QEQueue::post(), QP::QEQueue::postLIFO(), QP::QEQueue::get()
Description
Retrieves an event from the front of the "raw" thread-safe queue and returns a pointer to this event to the caller.
Parameters
[in]qs_idQS-id of this state machine (for QS local filter)
Returns
pointer to event at the front of the queue, if the queue is not empty and NULL if the queue is empty.
Note
this function is used for the "raw" thread-safe queues and not for the queues of active objects.
See also
QP::QEQueue::post(), QP::QEQueue::postLIFO(), QP::QActive::recall()

Definition at line 287 of file qf_qeq.cpp.

◆ getNFree()

QEQueueCtr getNFree ( void  ) const
inlinenoexcept

"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
QP::QMActive::defer(), QP::QMActive::recall()

Definition at line 225 of file qequeue.hpp.

◆ getNMin()

QEQueueCtr getNMin ( void  ) const
inlinenoexcept

"raw" thread-safe QF event queue operation for obtaining the minimum number of free entries ever in the queue (a.k.a. "low-watermark").

Description
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.
Returns
the minimum number of free entries ever in the queue since init.

Definition at line 240 of file qequeue.hpp.

◆ isEmpty()

bool isEmpty ( void  ) const
inlinenoexcept

"raw" thread-safe QF event queue operation to find out if the queue is empty

Note
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.
See also
QP::QMActive::defer(), QP::QMActive::recall()

Definition at line 254 of file qequeue.hpp.

◆ operator=()

QEQueue& operator= ( QEQueue const &  )
privatedelete

disallow assignment of QEQueue

Friends And Related Function Documentation

◆ QF

friend class QF
friend

Definition at line 265 of file qequeue.hpp.

◆ QActive

friend class QActive
friend

Definition at line 266 of file qequeue.hpp.

◆ QXThread

friend class QXThread
friend

Definition at line 267 of file qequeue.hpp.

◆ QTicker

friend class QTicker
friend

Definition at line 268 of file qequeue.hpp.

◆ QS

friend class QS
friend

Definition at line 269 of file qequeue.hpp.

Field Documentation

◆ m_frontEvt

QEvt const* volatile m_frontEvt
private

pointer to event at the front of the queue

Description
All incoming and outgoing events pass through the m_frontEvt location. When the queue is empty (which is most of the time), the extra m_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 m_frontEvt location is NULL.

Definition at line 136 of file qequeue.hpp.

◆ m_ring

QEvt const** m_ring
private

pointer to the start of the ring buffer

Definition at line 139 of file qequeue.hpp.

◆ m_end

QEQueueCtr m_end
private

offset of the end of the ring buffer from the start of the buffer

Definition at line 142 of file qequeue.hpp.

◆ m_head

QEQueueCtr volatile m_head
private

offset to where next event will be inserted into the buffer

Definition at line 145 of file qequeue.hpp.

◆ m_tail

QEQueueCtr volatile m_tail
private

offset of where next event will be extracted from the buffer

Definition at line 148 of file qequeue.hpp.

◆ m_nFree

QEQueueCtr volatile m_nFree
private

number of free events in the ring buffer

Definition at line 151 of file qequeue.hpp.

◆ m_nMin

QEQueueCtr m_nMin
private

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
QP::QF::getQueueMin().

Definition at line 157 of file qequeue.hpp.


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