qOS::queue Class Reference

A Queue object. More...

#include <queue.hpp>

Public Member Functions
	queue ()=default
bool	setup (void *pData, const size_t size, const size_t count) noexcept
	Configures a Queue. Here, the RAM used to hold the queue data pData is statically allocated at compile time by the application writer.
template<typename T >
bool	setup (void *pData, const size_t count) noexcept
	Configures a Queue. Here, the RAM used to hold the queue data pData is statically allocated at compile time by the application writer.
void	reset (void) noexcept
	Resets a queue to its original empty state.
bool	isEmpty (void) const noexcept
	Returns the empty status of the Queue.
bool	isFull (void) const noexcept
	Returns the full status of the Queue.
size_t	count (void) const noexcept
	Returns the number of items in the Queue.
size_t	itemsAvailable (void) const noexcept
	Returns the number of available slots to hold items inside the queue.
bool	removeFront (void) noexcept
	Remove the data located at the front of the Queue.
bool	receive (void *dst) noexcept
	Receive an item from a queue (and removes it). The item is received by copy so a buffer of adequate size must be provided. The number of bytes copied into the buffer was defined when the queue was created.
bool	send (void *itemToQueue, const queueSendMode pos=queueSendMode::TO_BACK) noexcept
	Post an item to the the queue. The item is queued by copy, not by reference.
void *	peek (void) const noexcept
	Looks at the data from the front of the Queue without removing it.
bool	isInitialized (void) const noexcept
	Check if the queue is already initialized by using queue::setup()
size_t	getItemSize (void) const noexcept
	Get the size(in bytes) used for every item in the queue.

Detailed Description

A Queue object.

A queue is a linear data structure with simple operations based on the FIFO (First In First Out) principle. It is capable to hold a finite number of fixed-size data items. The maximum number of items that a queue can hold is called its length. Both the length and the size of each data item are set when the queue is created.

In general, this kind of data structure is used to serialize data between tasks, allowing some elasticity in time. In many cases, the queue is used as a data buffer in interrupt service routines. This buffer will collect the data so, at some later time, another task can fetch the data for further processing. This use case is the single "task to task" buffering case. There are also other applications for queues as serializing many data streams into one receiving streams (multiple tasks to a single task) or vice-versa (single task to multiple tasks).

The queue::setup() method configures the queue and initialize the instance. The required RAM for the queue data should be provided by the application writer and could be statically allocated at compile time or in run-time using the memory management extension.

Constructor & Destructor Documentation

queue()

qOS::queue::queue ( )

default

Member Function Documentation

count()

size_t qOS::queue::count ( void ) const

noexcept

Returns the number of items in the Queue.

Returns

The number of elements in the queue

getItemSize()

size_t qOS::queue::getItemSize ( void ) const

noexcept

Get the size(in bytes) used for every item in the queue.

Returns

The item-size in bytes.

isEmpty()

bool qOS::queue::isEmpty ( void ) const

noexcept

Returns the empty status of the Queue.

Returns

true if the Queue is empty, false if it is not.

isFull()

bool qOS::queue::isFull ( void ) const

noexcept

Returns the full status of the Queue.

Returns

true if the Queue is full, false if it is not.

isInitialized()

bool qOS::queue::isInitialized ( void ) const

noexcept

Check if the queue is already initialized by using queue::setup()

Returns

true if the queue is initialized, false if not.

itemsAvailable()

size_t qOS::queue::itemsAvailable ( void ) const

noexcept

Returns the number of available slots to hold items inside the queue.

Returns

The number of available slots in the queue.

peek()

void * qOS::queue::peek ( void ) const

noexcept

Looks at the data from the front of the Queue without removing it.

Returns

Pointer to the data, or nullptr if there is nothing in the queue.

receive()

bool qOS::queue::receive ( void * dst )

noexcept

Receive an item from a queue (and removes it). The item is received by copy so a buffer of adequate size must be provided. The number of bytes copied into the buffer was defined when the queue was created.

Parameters

[out]

dst

Pointer to the buffer into which the received item will be copied.

Returns

true if data was retrieved from the Queue, otherwise returns false

removeFront()

bool qOS::queue::removeFront ( void )

noexcept

Remove the data located at the front of the Queue.

Returns

true if data was removed from the Queue, otherwise returns false

reset()

void qOS::queue::reset ( void )

noexcept

Resets a queue to its original empty state.

send()

bool qOS::queue::send ( void * itemToQueue, const queueSendMode pos = queueSendMode::TO_BACK )

noexcept

Post an item to the the queue. The item is queued by copy, not by reference.

Parameters

[in]	itemToQueue	A pointer to the item that is to be placed on the queue. The size of the items the queue will hold was defined when the queue was created, so this many bytes will be copied from itemToQueue into the queue storage area.
[in]	pos	Can take the value queueSendMode::TO_BACK (default) to place the item at the back of the queue, or queueSendMode::TO_FRONT to place the item at the front of the queue (for high priority messages).

Returns

true on successful add, false if not added

setup() [1/2]

template<typename T >

bool qOS::queue::setup ( void * pData, const size_t count )

inlinenoexcept

Configures a Queue. Here, the RAM used to hold the queue data pData is statically allocated at compile time by the application writer.

Template Parameters

T	Type of one single item in the queue

Parameters

[in]	pData	Data block or array of data (Queue storage area).
[in]	count	The maximum number of items the queue can hold.

Returns

true on success, otherwise returns false.

setup() [2/2]

bool qOS::queue::setup ( void * pData, const size_t size, const size_t count )

noexcept

Configures a Queue. Here, the RAM used to hold the queue data pData is statically allocated at compile time by the application writer.

Parameters

[in]	pData	Data block or array of data (Queue storage area).
[in]	size	The size, in bytes, of one single item in the queue.
[in]	count	The maximum number of items the queue can hold.

Returns

true on success, otherwise returns false.