FastArduino  v1.7
C++ library to build fast but small Arduino/AVR projects
containers::Queue< T_, TREF_ > Class Template Reference

Queue of type T_ items. More...

#include <fastarduino/queue.h>

Public Types

using T = T_
 The type of items in this queue.
 
using TREF = TREF_
 The constant reference type of items in this queue.
 

Public Member Functions

 Queue (const Queue< T_, TREF_ > &)=delete
 
Queue< T_, TREF_ > & operator= (const Queue< T_, TREF_ > &)=delete
 
template<uint8_t SIZE>
 Queue (T(&buffer)[SIZE], bool locked=false)
 Create a new queue, based on the provided buffer array. More...
 
void lock ()
 Lock this queue, ie prevent pushing any data to it. More...
 
void unlock ()
 Unlock this queue, ie allow pushing data to it. More...
 
bool is_locked () const
 Check if this queue is locked, ie if pushing data to it is disabled. More...
 
bool push_ (TREF item)
 Push item to the end of this queue, provided there is still available space in its ring buffer. More...
 
bool pull_ (T &item)
 Pull an item from the beginning of this queue, if not empty, and copy it into item. More...
 
bool peek_ (T &item) const
 Peek an item from the beginning of this queue, if not empty, and copy it into item. More...
 
uint8_t peek_ (T *buffer, uint8_t size) const
 Peek up to size items from the beginning of this queue, if not empty, and copy these into buffer array. More...
 
template<uint8_t SIZE>
uint8_t peek_ (T(&buffer)[SIZE]) const
 Peek up to SIZE items from the beginning of this queue, if not empty, and copy these into buffer array. More...
 
uint8_t size () const
 Get the maximum size of this queue. More...
 
bool empty_ () const
 Tell if this queue is currently empty. More...
 
bool full_ () const
 Tell if this queue is currently full. More...
 
uint8_t items_ () const
 Tell the current number of items currently present in this queue. More...
 
uint8_t free_ () const
 Tell the current number of available locations for items to be pushed to this queue. More...
 
void clear_ ()
 Completely clear this queue. More...
 
bool push (TREF item)
 Push item to the end of this queue, provided there is still available space in its ring buffer. More...
 
bool pull (T &item)
 Pull an item from the beginning of this queue, if not empty, and copy it into item. More...
 
bool peek (T &item) const
 Peek an item from the beginning of this queue, if not empty, and copy it into item. More...
 
uint8_t peek (T *buffer, uint8_t size) const
 Peek up to size items from the beginning of this queue, if not empty, and copy these into buffer array. More...
 
template<uint8_t SIZE>
uint8_t peek (T(&buffer)[SIZE]) const
 Peek up to SIZE items from the beginning of this queue, if not empty, and copy these into buffer array. More...
 
bool empty () const
 Tell if this queue is currently empty. More...
 
uint8_t items () const
 Tell the current number of items currently present in this queue. More...
 
uint8_t free () const
 Tell the current number of available locations for items to be pushed to this queue. More...
 
bool full () const
 Tell if this queue is currently full. More...
 
void clear ()
 Completely clear this queue. More...
 

Detailed Description

template<typename T_, typename TREF_ = const T_&>
class containers::Queue< T_, TREF_ >

Queue of type T_ items.

This is a FIFO (first in first out) queue, built upon a ring buffer of fixed size, passed at construction time.

This queue offers only a few operations:

  • push an item at "the end" of the queue
  • pull an item from "the beginning" of the queue
  • clear the whole queue
  • get various information without changing the queue, including peeking one or several items from the beginning of the queue without removing them

All operations exist in two flavors:

  • synchronized: you should use this flavor whenever the caller cannot guarantee no interruption will occur during the operation, i.e. when the caller is neither part of an ISR, nor embedded itself in a synchronized block.
  • not synchronized: you should use this flavor when the caller can guarantee that no interruption will occur during the operation, e.g. when called from an ISR or from within a synchronized block; these methods bear the same name as their synchronized counterparts, with an additional trailing **_** underscore.
Template Parameters
T_the type of items in this queue
TREF_the constant reference type of items in this queue; this is const T_& by default, but this may be changed, for small size types (one or two bytes long) to T_ itself, in order to avoid additional code to handle reference extraction of an item. This type is used by push() methods.

Definition at line 58 of file queue.h.

Constructor & Destructor Documentation

◆ Queue()

template<typename T_ , typename TREF_ = const T_&>
template<uint8_t SIZE>
containers::Queue< T_, TREF_ >::Queue ( T(&)  buffer[SIZE],
bool  locked = false 
)
inlineexplicit

Create a new queue, based on the provided buffer array.

The queue size is determined by the size of buffer.

Template Parameters
SIZEthe number of T items that buffer can hold; note that, for optimization reasons, only SIZE - 1 items can be held in the buffer.
Parameters
bufferthe buffer used by this queue to store its items
lockedwhen true, prevents pushing any data to this queue

Definition at line 78 of file queue.h.

Member Function Documentation

◆ lock()

template<typename T_ , typename TREF_ = const T_&>
void containers::Queue< T_, TREF_ >::lock ( )
inline

Lock this queue, ie prevent pushing any data to it.

See also
unlock()
is_locked()

Definition at line 86 of file queue.h.

◆ unlock()

template<typename T_ , typename TREF_ = const T_&>
void containers::Queue< T_, TREF_ >::unlock ( )
inline

Unlock this queue, ie allow pushing data to it.

See also
lock()
is_locked()

Definition at line 96 of file queue.h.

◆ is_locked()

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::is_locked ( ) const
inline

Check if this queue is locked, ie if pushing data to it is disabled.

See also
lock()
unlock()

Definition at line 106 of file queue.h.

◆ push_()

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::push_ ( TREF  item)

Push item to the end of this queue, provided there is still available space in its ring buffer.

This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor push() instead.

Parameters
itema constant reference to the item to be pushed to thsi queue
Return values
trueif item could be pushed
falseif this queue is full and thus item could not be pushed
See also
push()
pull_()
free_()

◆ pull_()

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::pull_ ( T item)

Pull an item from the beginning of this queue, if not empty, and copy it into item.

The item is removed from the queue. This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor pull() instead.

Parameters
itema reference to the item variable that will be assigned the first element of this queue
Return values
trueif the queue is not empty and thus an item has been copied to item
falseif this queue is empty and thus item has not changed
See also
pull()
push_()
empty_()

◆ peek_() [1/3]

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::peek_ ( T item) const

Peek an item from the beginning of this queue, if not empty, and copy it into item.

The queue is NOT modified, no item is removed from the queue. This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor peek() instead.

Parameters
itema reference to the item variable that will be assigned the first element of this queue
Return values
trueif the queue is not empty and thus an item has been copied to item
falseif this queue is empty and thus item has not changed
See also
peek()
pull_()
push_()
empty_()

◆ peek_() [2/3]

template<typename T_ , typename TREF_ = const T_&>
uint8_t containers::Queue< T_, TREF_ >::peek_ ( T buffer,
uint8_t  size 
) const

Peek up to size items from the beginning of this queue, if not empty, and copy these into buffer array.

The queue is NOT modified, no item is removed from the queue. This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor peek() instead.

Parameters
buffera pointer to an array of size items of type T, that will be assigned the first size elements of this queue
sizethe maximum number of items to peek from this queue and copy to buffer; buffer size must be at least size
Returns
the number of elements copied from the queue into buffer; this may be 0 if the queue is empty, or any number lower or equal to size; this will be size if the queue has at least size elements
See also
peek()
pull_()
push_()
items_()

◆ peek_() [3/3]

template<typename T_ , typename TREF_ = const T_&>
template<uint8_t SIZE>
uint8_t containers::Queue< T_, TREF_ >::peek_ ( T(&)  buffer[SIZE]) const

Peek up to SIZE items from the beginning of this queue, if not empty, and copy these into buffer array.

The queue is NOT modified, no item is removed from the queue. This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor peek() instead.

Template Parameters
SIZEthe number of items that buffer can hold; this is also the maximum number of items to peek from this queue and copy to buffer
Parameters
bufferan array of SIZE items of type T, that will be assigned the first SIZE elements of this queue
Returns
the number of elements copied from the queue into buffer; this may be 0 if the queue is empty, or any number lower or equal to SIZE; this will be SIZE if the queue has at least SIZE elements
See also
peek()
pull_()
push_()
items_()

◆ size()

template<typename T_ , typename TREF_ = const T_&>
uint8_t containers::Queue< T_, TREF_ >::size ( ) const
inline

Get the maximum size of this queue.

This is the maximum number of items that can be present at the same time in this queue.

Definition at line 219 of file queue.h.

◆ empty_()

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::empty_ ( ) const
inline

Tell if this queue is currently empty.

This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor empty() instead.

See also
empty()
free_()
full_()

Definition at line 233 of file queue.h.

◆ full_()

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::full_ ( ) const
inline

Tell if this queue is currently full.

This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor full() instead.

See also
full()
free_()

Definition at line 246 of file queue.h.

◆ items_()

template<typename T_ , typename TREF_ = const T_&>
uint8_t containers::Queue< T_, TREF_ >::items_ ( ) const
inline

Tell the current number of items currently present in this queue.

This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor items() instead.

See also
items()
size()

Definition at line 259 of file queue.h.

◆ free_()

template<typename T_ , typename TREF_ = const T_&>
uint8_t containers::Queue< T_, TREF_ >::free_ ( ) const
inline

Tell the current number of available locations for items to be pushed to this queue.

This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor free() instead.

See also
free()
empty_()

Definition at line 275 of file queue.h.

◆ clear_()

template<typename T_ , typename TREF_ = const T_&>
void containers::Queue< T_, TREF_ >::clear_ ( )
inline

Completely clear this queue.

All present items, if any, are lost. This method is not synchronized, hence you must ensure it is called from an interrupt-safe context; otherwise, you should use the synchronized flavor clear() instead.

See also
clear()
empty_()

Definition at line 291 of file queue.h.

◆ push()

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::push ( TREF  item)
inline

Push item to the end of this queue, provided there is still available space in its ring buffer.

This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor push_() instead.

Parameters
itema constant reference to the item to be pushed to thsi queue
Return values
trueif item could be pushed
falseif this queue is full and thus item could not be pushed
See also
push_()
pull()
free()

Definition at line 311 of file queue.h.

◆ pull()

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::pull ( T item)
inline

Pull an item from the beginning of this queue, if not empty, and copy it into item.

The item is removed from the queue. This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor pull_() instead.

Parameters
itema reference to the item variable that will be assigned the first element of this queue
Return values
trueif the queue is not empty and thus an item has been copied to item
falseif this queue is empty and thus item has not changed
See also
pull_()
push()
empty()

Definition at line 333 of file queue.h.

◆ peek() [1/3]

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::peek ( T item) const
inline

Peek an item from the beginning of this queue, if not empty, and copy it into item.

The queue is NOT modified, no item is removed from the queue. This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor peek_() instead.

Parameters
itema reference to the item variable that will be assigned the first element of this queue
Return values
trueif the queue is not empty and thus an item has been copied to item
falseif this queue is empty and thus item has not changed
See also
peek_()
pull()
push()
empty()

Definition at line 356 of file queue.h.

◆ peek() [2/3]

template<typename T_ , typename TREF_ = const T_&>
uint8_t containers::Queue< T_, TREF_ >::peek ( T buffer,
uint8_t  size 
) const
inline

Peek up to size items from the beginning of this queue, if not empty, and copy these into buffer array.

The queue is NOT modified, no item is removed from the queue. This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor peek_() instead.

Parameters
buffera pointer to an array of size items of type T, that will be assigned the first size elements of this queue
sizethe maximum number of items to peek from this queue and copy to buffer; buffer size must be at least size
Returns
the number of elements copied from the queue into buffer; this may be 0 if the queue is empty, or any number lower or equal to size; this will be size if the queue has at least size elements
See also
peek_()
pull()
push()
items()

Definition at line 382 of file queue.h.

◆ peek() [3/3]

template<typename T_ , typename TREF_ = const T_&>
template<uint8_t SIZE>
uint8_t containers::Queue< T_, TREF_ >::peek ( T(&)  buffer[SIZE]) const
inline

Peek up to SIZE items from the beginning of this queue, if not empty, and copy these into buffer array.

The queue is NOT modified, no item is removed from the queue. This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor peek_() instead.

Template Parameters
SIZEthe number of items that buffer can hold; this is also the maximum number of items to peek from this queue and copy to buffer
Parameters
bufferan array of SIZE items of type T, that will be assigned the first SIZE elements of this queue
Returns
the number of elements copied from the queue into buffer; this may be 0 if the queue is empty, or any number lower or equal to SIZE; this will be SIZE if the queue has at least SIZE elements
See also
peek_()
pull()
push()
items()

Definition at line 409 of file queue.h.

◆ empty()

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::empty ( ) const
inline

Tell if this queue is currently empty.

This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor empty_() instead.

Definition at line 420 of file queue.h.

◆ items()

template<typename T_ , typename TREF_ = const T_&>
uint8_t containers::Queue< T_, TREF_ >::items ( ) const
inline

Tell the current number of items currently present in this queue.

This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor items_() instead.

See also
items_()

Definition at line 432 of file queue.h.

◆ free()

template<typename T_ , typename TREF_ = const T_&>
uint8_t containers::Queue< T_, TREF_ >::free ( ) const
inline

Tell the current number of available locations for items to be pushed to this queue.

This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor free_() instead.

See also
free_()
empty()

Definition at line 446 of file queue.h.

◆ full()

template<typename T_ , typename TREF_ = const T_&>
bool containers::Queue< T_, TREF_ >::full ( ) const
inline

Tell if this queue is currently full.

This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor full_() instead.

See also
full_()
free()

Definition at line 459 of file queue.h.

◆ clear()

template<typename T_ , typename TREF_ = const T_&>
void containers::Queue< T_, TREF_ >::clear ( )
inline

Completely clear this queue.

All present items, if any, are lost. This method is synchronized, hence you can call it from an an interrupt-unsafe context; if you are sure you are in an interrupt-safe, you should use the not synchronized flavor free() instead.

See also
clear_()
empty()

Definition at line 472 of file queue.h.


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