Native QF Event Queue. More...

#include <qequeue.hpp>

Public Member Functions
	QEQueue () noexcept
	Default constructor of QP::QEQueue.
void	init (QEvt const **const qSto, std::uint_fast16_t const qLen) noexcept
	Initialize the native QF event queue.
bool	post (QEvt const *const e, std::uint_fast16_t const margin, std::uint_fast8_t const qsId) noexcept
	Post an event to the "raw" thread-safe event queue (FIFO).
void	postLIFO (QEvt const *const e, std::uint_fast8_t const qsId) noexcept
	Post an event to the "raw" thread-safe event queue (LIFO).
QEvt const *	get (std::uint_fast8_t const qsId) noexcept
	Obtain an event from the "raw" thread-safe queue.
std::uint16_t	getFree () const noexcept
	Obtain the number of free entries still available in the queue.
std::uint16_t	getUse () const noexcept
	Obtain the number of entries in use in the queue.
std::uint16_t	getMin () const noexcept
	Obtain the minimum number of free entries ever in the queue (a.k.a. "low-watermark").
bool	isEmpty () const noexcept
	Find out if the queue is empty.
QEvt const *	peekFront () const &
QEvt const *	peekFront () &&=delete

Private Member Functions
void	postFIFO_ (QEvt const const e, void const const sender)

Private Attributes
QEvt const *	m_frontEvt
	Pointer to event at the front of the queue.
QEvt const **	m_ring
	Pointer to the start of the ring buffer.
QEQueueCtr	m_end
	Offset of the end of the ring buffer from the start of the buffer.
QEQueueCtr	m_head
	Offset to where next event will be inserted into the buffer.
QEQueueCtr	m_tail
	Offset of where next event will be extracted from the buffer.
QEQueueCtr	m_nFree
	Number of free events in the ring buffer.
QEQueueCtr	m_nMin
	Minimum number of free events ever in the ring buffer.

Friends
class	QActive
class	QTicker
class	QXMutex
class	QXThread
class	QS

Detailed Description

Native QF Event Queue.

Details
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 QP::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 QP::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_().

The other set of functions uses QP::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.

See also: QP::QEQueue for the description of the data members

Definition at line 53 of file qequeue.hpp.

Constructor & Destructor Documentation

◆ QEQueue()

QP::QEQueue::QEQueue ( )

noexcept

Default constructor of QP::QEQueue.

Definition at line 48 of file qf_qeq.cpp.

Member Function Documentation

◆ init()

void QP::QEQueue::init	(	QEvt const **const	qSto,
		std::uint_fast16_t const	qLen )

noexcept

Initialize the native QF event queue.

Details
Initialize the event queue by giving it the storage for the ring buffer.

Parameters

[in]	qSto	an array of ::QEvtPtr to serve as the ring buffer for the event queue
[in]	qLen	the 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-in QV and QK kernels, as well as other QP ports to OSes/RTOSes that do provide a suitable message queue.

Definition at line 58 of file qf_qeq.cpp.

◆ post()

bool QP::QEQueue::post	(	QEvt const *const	e,
		std::uint_fast16_t const	margin,
		std::uint_fast8_t const	qsId )

noexcept

Post an event to the "raw" thread-safe event queue (FIFO).

Details
Post an event to the "raw" thread-safe event queue using the First-In-First-Out (FIFO) order.

Parameters

[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 QP::QF::NO_MARGIN means that this function will assert if posting
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns: 'true' (success) when the posting succeeded with the provided margin and 'false' (failure) when the posting fails.

Note: The QP::QF::NO_MARGIN value of the margin parameter is special and denotes a situation when the post() operation is assumed to succeed (event delivery guarantee). An assertion fires when the event cannot be delivered.; This function can be called from any task context or ISR context.

See also

QEQueue::postLIFO()
QEQueue::get()

Definition at line 84 of file qf_qeq.cpp.

◆ postLIFO()

void QP::QEQueue::postLIFO	(	QEvt const *const	e,
		std::uint_fast8_t const	qsId )

noexcept

Post an event to the "raw" thread-safe event queue (LIFO).

Details
Post an event to the "raw" thread-safe event queue using the Last-In-First-Out (LIFO) order.

Parameters

[in]	e	pointer to the event to be posted to the queue
[in]	qsId	QS-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

QEQueue::post()
QEQueue::get()
QActive::defer()

Definition at line 164 of file qf_qeq.cpp.

◆ get()

QEvt const * QP::QEQueue::get ( std::uint_fast8_t const qsId )

noexcept

Obtain an event from the "raw" thread-safe queue.

Details
Retrieves an event from the front of the "raw" thread-safe queue and returns a pointer to this event to the caller.

Parameters

[in] qsId QS-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

QEQueue::post()
QEQueue::postLIFO()
QActive::recall()

Definition at line 220 of file qf_qeq.cpp.

◆ getFree()

std::uint16_t QP::QEQueue::getFree ( ) const

noexcept

Obtain the number of free entries still available in the queue.

Details
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.

Returns: the current number of free slots in the queue.

Definition at line 294 of file qf_qeq.cpp.

◆ getUse()

std::uint16_t QP::QEQueue::getUse ( ) const

noexcept

Obtain the number of entries in use in the queue.

Details
This operation needs to be used with caution because the number of entries in use 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.

Returns: the current number of used slots in the queue.

Definition at line 282 of file qf_qeq.cpp.

◆ getMin()

std::uint16_t QP::QEQueue::getMin ( ) const

noexcept

Obtain the minimum number of free entries ever in the queue (a.k.a. "low-watermark").

Details
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 300 of file qf_qeq.cpp.

◆ isEmpty()

bool QP::QEQueue::isEmpty ( ) const

noexcept

Find out if the queue is empty.

Details
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.

Returns: 'true' if the queue is currently empty and 'false' otherwise.

Definition at line 306 of file qf_qeq.cpp.

◆ peekFront() [1/2]

QEvt const * QP::QEQueue::peekFront ( ) const &

Definition at line 312 of file qf_qeq.cpp.

◆ peekFront() [2/2]

QEvt const * QP::QEQueue::peekFront ( ) &&

delete

◆ postFIFO_()

void QP::QEQueue::postFIFO_	(	QEvt const *const	e,
		void const *const	sender )

private

◆ QActive

friend class QActive

friend

Definition at line 90 of file qequeue.hpp.

◆ QTicker

friend class QTicker

friend

Definition at line 91 of file qequeue.hpp.

◆ QXMutex

friend class QXMutex

friend

Definition at line 92 of file qequeue.hpp.

◆ QXThread

friend class QXThread

friend

Definition at line 93 of file qequeue.hpp.

◆ QS

friend class QS

friend

Definition at line 94 of file qequeue.hpp.

Member Data Documentation

◆ m_frontEvt

QEvt const* QP::QEQueue::m_frontEvt

private

Pointer to event at the front of the queue.

Details
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 bypassing the ring buffer altogether, significantly 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.

Definition at line 77 of file qequeue.hpp.

◆ m_ring

QEvt const* * QP::QEQueue::m_ring

private

Pointer to the start of the ring buffer.

Definition at line 78 of file qequeue.hpp.

◆ m_end

QEQueueCtr QP::QEQueue::m_end

private

Offset of the end of the ring buffer from the start of the buffer.

Definition at line 79 of file qequeue.hpp.

◆ m_head

QEQueueCtr QP::QEQueue::m_head

private

Offset to where next event will be inserted into the buffer.

Definition at line 80 of file qequeue.hpp.

◆ m_tail

QEQueueCtr QP::QEQueue::m_tail

private

Offset of where next event will be extracted from the buffer.

Definition at line 81 of file qequeue.hpp.

◆ m_nFree

QEQueueCtr QP::QEQueue::m_nFree

private

Number of free events in the ring buffer.

Definition at line 82 of file qequeue.hpp.

◆ m_nMin

QEQueueCtr QP::QEQueue::m_nMin

private

Minimum number of free events ever in the ring buffer.

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

See also: QF::getQueueMargin()

Definition at line 83 of file qequeue.hpp.

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


QP/C++ 8.1.2 Real-Time Event Framework

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ QEQueue()

Member Function Documentation

◆ init()

◆ post()

◆ postLIFO()

◆ get()

◆ getFree()

◆ getUse()

◆ getMin()

◆ isEmpty()

◆ peekFront() [1/2]

◆ peekFront() [2/2]

◆ postFIFO_()

Friends And Related Symbol Documentation

◆ QActive

◆ QTicker

◆ QXMutex

◆ QXThread

◆ QS

Member Data Documentation

◆ m_frontEvt

◆ m_ring

◆ m_end

◆ m_head

◆ m_tail

◆ m_nFree

◆ m_nMin