circular_queue< T, ForEachArg > Class Template Reference

Instance class for a single-producer, single-consumer circular queue / ring buffer (FIFO). This implementation is lock-free between producer and consumer for the available(), peek(), pop(), and push() type functions. More...

#include <circular_queue.h>

Inherited by circular_queue_mp< T, ForEachArg > [protected].

Public Member Functions
	circular_queue ()
	Constructs a valid, but zero-capacity dummy queue.
	circular_queue (const size_t capacity)
	Constructs a queue of the given maximum capacity.
	circular_queue (circular_queue &&cq)
	~circular_queue ()
	circular_queue (const circular_queue &)=delete
circular_queue &	operator= (circular_queue &&cq)
circular_queue &	operator= (const circular_queue &)=delete
size_t	capacity () const
	Get the numer of elements the queue can hold at most.
bool	capacity (const size_t cap)
	Resize the queue. The available elements in the queue are preserved. This is not lock-free and concurrent producer or consumer access will lead to corruption.
void	flush ()
	Discard all data in the queue.
size_t	available () const
	Get a snapshot number of elements that can be retrieved by pop.
size_t	available_for_push () const
	Get the remaining free elementes for pushing.
T	peek () const
	Peek at the next element pop will return without removing it from the queue.
T &IRAM_ATTR	pushpeek () __attribute__((always_inline))
	Peek at the next pending input value.
bool IRAM_ATTR	push () __attribute__((always_inline))
	Release the next pending input value, accessible by pushpeek(), into the queue.
bool IRAM_ATTR	push (T &&val) __attribute__((always_inline))
	Move the rvalue parameter into the queue.
bool IRAM_ATTR	push (const T &val) __attribute__((always_inline))
	Push a copy of the parameter into the queue.
size_t	push_n (const T *buffer, size_t size)
	Push copies of multiple elements from a buffer into the queue, in order, beginning at buffer's head.
T	pop ()
	Pop the next available element from the queue.
size_t	pop_n (T *buffer, size_t size)
	Pop multiple elements in ordered sequence from the queue to a buffer. If buffer is nullptr, simply discards up to size elements from the queue.
void	for_each (const Delegate< void(T &&), ForEachArg > &fun)
	Iterate over and remove each available element from queue, calling back fun with an rvalue reference of every single element.
void	for_each (Delegate< void(T &&), ForEachArg > fun)
bool	for_each_rev_requeue (const Delegate< bool(T &), ForEachArg > &fun)
	In reverse order, iterate over, pop and optionally requeue each available element from the queue, calling back fun with a reference of every single element. Requeuing is dependent on the return boolean of the callback function. If it returns true, the requeue occurs.
bool	for_each_rev_requeue (Delegate< bool(T &), ForEachArg > fun)

Protected Attributes
const T	defaultValue = {}
size_t	m_bufSize
std::unique_ptr< T[]>	m_buffer
std::unique_ptr< T >	m_buffer
std::atomic< size_t >	m_inPos
std::atomic< size_t >	m_outPos

Detailed Description

template<typename T, typename ForEachArg = void>
class circular_queue< T, ForEachArg >

Instance class for a single-producer, single-consumer circular queue / ring buffer (FIFO). This implementation is lock-free between producer and consumer for the available(), peek(), pop(), and push() type functions.

Constructor & Destructor Documentation

circular_queue() [1/4]

template<typename T , typename ForEachArg = void>

circular_queue< T, ForEachArg >::circular_queue ( )

inline

Constructs a valid, but zero-capacity dummy queue.

circular_queue() [2/4]

template<typename T , typename ForEachArg = void>

circular_queue< T, ForEachArg >::circular_queue ( const size_t  capacity )

inline

Constructs a queue of the given maximum capacity.

circular_queue() [3/4]

template<typename T , typename ForEachArg = void>

circular_queue< T, ForEachArg >::circular_queue ( circular_queue< T, ForEachArg > &&  cq )

inline

~circular_queue()

template<typename T , typename ForEachArg = void>

circular_queue< T, ForEachArg >::~circular_queue ( )

inline

circular_queue() [4/4]

template<typename T , typename ForEachArg = void>

circular_queue< T, ForEachArg >::circular_queue ( const circular_queue< T, ForEachArg > &  )

delete

Member Function Documentation

available()

template<typename T , typename ForEachArg = void>

size_t circular_queue< T, ForEachArg >::available ( ) const

inline

Get a snapshot number of elements that can be retrieved by pop.

available_for_push()

template<typename T , typename ForEachArg = void>

size_t circular_queue< T, ForEachArg >::available_for_push ( ) const

inline

Get the remaining free elementes for pushing.

capacity() [1/2]

template<typename T , typename ForEachArg = void>

size_t circular_queue< T, ForEachArg >::capacity ( ) const

inline

Get the numer of elements the queue can hold at most.

capacity() [2/2]

template<typename T , typename ForEachArg >

bool circular_queue< T, ForEachArg >::capacity

(

const size_t

cap

)

Resize the queue. The available elements in the queue are preserved. This is not lock-free and concurrent producer or consumer access will lead to corruption.

Returns

True if the new capacity could accommodate the present elements in the queue, otherwise nothing is done and false is returned.

flush()

template<typename T , typename ForEachArg = void>

void circular_queue< T, ForEachArg >::flush ( )

inline

Discard all data in the queue.

for_each() [1/2]

template<typename T , typename ForEachArg >

void circular_queue< T, ForEachArg >::for_each

(

const Delegate< void(T &&), ForEachArg > &

fun

)

Iterate over and remove each available element from queue, calling back fun with an rvalue reference of every single element.

for_each() [2/2]

template<typename T , typename ForEachArg = void>

void circular_queue< T, ForEachArg >::for_each

(

Delegate< void(T &&), ForEachArg >

fun

)

for_each_rev_requeue() [1/2]

template<typename T , typename ForEachArg >

bool circular_queue< T, ForEachArg >::for_each_rev_requeue

(

const Delegate< bool(T &), ForEachArg > &

fun

)

In reverse order, iterate over, pop and optionally requeue each available element from the queue, calling back fun with a reference of every single element. Requeuing is dependent on the return boolean of the callback function. If it returns true, the requeue occurs.

for_each_rev_requeue() [2/2]

template<typename T , typename ForEachArg = void>

bool circular_queue< T, ForEachArg >::for_each_rev_requeue

(

Delegate< bool(T &), ForEachArg >

fun

)

operator=() [1/2]

template<typename T , typename ForEachArg = void>

circular_queue & circular_queue< T, ForEachArg >::operator= ( circular_queue< T, ForEachArg > &&  cq )

inline

operator=() [2/2]

template<typename T , typename ForEachArg = void>

circular_queue & circular_queue< T, ForEachArg >::operator= ( const circular_queue< T, ForEachArg > &  )

delete

peek()

template<typename T , typename ForEachArg = void>

T circular_queue< T, ForEachArg >::peek ( ) const

inline

Peek at the next element pop will return without removing it from the queue.

Returns

An rvalue copy of the next element that can be popped. If the queue is empty, return an rvalue copy of the element that is pending the next push.

pop()

template<typename T , typename ForEachArg >

T circular_queue< T, ForEachArg >::pop

Pop the next available element from the queue.

Returns

An rvalue copy of the popped element, or a default value of type T if the queue is empty.

pop_n()

template<typename T , typename ForEachArg >

size_t circular_queue< T, ForEachArg >::pop_n	(	T *	buffer,
		size_t	size
	)

Pop multiple elements in ordered sequence from the queue to a buffer. If buffer is nullptr, simply discards up to size elements from the queue.

Returns

The number of elements actually popped from the queue to buffer.

push() [1/3]

template<typename T , typename ForEachArg = void>

bool IRAM_ATTR circular_queue< T, ForEachArg >::push ( )

inline

Release the next pending input value, accessible by pushpeek(), into the queue.

Returns

true if the queue accepted the value, false if the queue was full.

push() [2/3]

template<typename T , typename ForEachArg = void>

bool IRAM_ATTR circular_queue< T, ForEachArg >::push ( const T &  val )

inline

Push a copy of the parameter into the queue.

Returns

true if the queue accepted the value, false if the queue was full.

push() [3/3]

template<typename T , typename ForEachArg = void>

bool IRAM_ATTR circular_queue< T, ForEachArg >::push ( T &&  val )

inline

Move the rvalue parameter into the queue.

Returns

true if the queue accepted the value, false if the queue was full.

push_n()

template<typename T , typename ForEachArg >

size_t circular_queue< T, ForEachArg >::push_n	(	const T *	buffer,
		size_t	size
	)

Push copies of multiple elements from a buffer into the queue, in order, beginning at buffer's head.

Returns

The number of elements actually copied into the queue, counted from the buffer head.

pushpeek()

template<typename T , typename ForEachArg = void>

T &IRAM_ATTR circular_queue< T, ForEachArg >::pushpeek ( )

inline

Peek at the next pending input value.

Returns

A reference to the next element that can be pushed.

Member Data Documentation

defaultValue

template<typename T , typename ForEachArg = void>

const T circular_queue< T, ForEachArg >::defaultValue = {}

protected

m_buffer [1/2]

template<typename T , typename ForEachArg = void>

std::unique_ptr<T[]> circular_queue< T, ForEachArg >::m_buffer

protected

m_buffer [2/2]

template<typename T , typename ForEachArg = void>

std::unique_ptr<T> circular_queue< T, ForEachArg >::m_buffer

protected

m_bufSize

template<typename T , typename ForEachArg = void>

size_t circular_queue< T, ForEachArg >::m_bufSize

protected

m_inPos

template<typename T , typename ForEachArg = void>

std::atomic<size_t> circular_queue< T, ForEachArg >::m_inPos

protected

m_outPos

template<typename T , typename ForEachArg = void>

std::atomic<size_t> circular_queue< T, ForEachArg >::m_outPos

protected

---

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

• circular_queue.h