Cpl::Container::RingBuffer< ITEM > Class Template Reference

This template class implements a Ring Buffer. More...

Detailed Description

template<class ITEM>
class Cpl::Container::RingBuffer< ITEM >

This template class implements a Ring Buffer.

The size of the ring buffer is limited by number of bits in platform's 'unsigned' data type.

Thread/ISR Safety Notes:

• The only mutable (once the Ring buffer is created) data members of the class are the head/tail pointers and the buffer contents.
• The add() operation only modifies the tail pointer (but does read the head pointer)
• The remove() operation only modifies the head pointer (but does read the tail pointer).
• The clearTheBuffer() operation modifies both the head and tail pointers
• All other methods only read data members
• The implementation ASSUMES there is a single producer and a single consumer of the RingBuffer. And that ONLY the producer/consumer are the invoking operations on the RingBuffer.

Template Args: ITEM:= Type of the data stored in the Ring Buffer

#include <RingBuffer.h>

Inheritance diagram for Cpl::Container::RingBuffer< ITEM >:

Public Member Functions
	RingBuffer (unsigned numElements, ITEM memoryForElements[]) noexcept
	Constructor.
bool	remove (ITEM &dst) noexcept
	Removes the first item in the Buffer.
bool	add (const ITEM &item) noexcept
	The contents of 'item' will be copied into the Ring Buffer as the 'last' item in the buffer.
ITEM *	peekHead (void) const noexcept
	Returns a pointer to the first item in the Buffer.
ITEM *	peekTail (void) const noexcept
	Returns a pointer to the last item in the Buffer.
bool	isEmpty (void) const noexcept
	This method returns true if the Ring Buffer is empty.
bool	isFull (void) const noexcept
	This method returns true if the Ring Buffer is full.
unsigned	getNumItems (void) const noexcept
	This method returns the current number of items in the Ring Buffer.
unsigned	getMaxItems (void) const noexcept
	This method returns the maximum number of items that can be stored in the Ring buffer.
void	clearTheBuffer () noexcept
	Empties the Ring Buffer.
ITEM *	peekNextRemoveItems (unsigned &dstNumFlatElements) noexcept
	This method returns a pointer to the next item to be removed.
void	removeElements (unsigned numElementsToRemove) noexcept
	This method 'removes' N elements - that were removed using the pointer returned from peekNextRemoveItems - from the ring buffer.
ITEM *	peekNextAddItems (unsigned &dstNumFlatElements) noexcept
	This method returns a pointer to the next item to be added.
void	addElements (unsigned numElementsAdded) noexcept
	This method 'adds' N elements - that were populated using the pointer returned from peekNextAddItems - to the ring buffer.

Constructor & Destructor Documentation

RingBuffer()

template<class ITEM >

Cpl::Container::RingBuffer< ITEM >::RingBuffer ( unsigned  numElements, ITEM  memoryForElements[]  )

noexcept

Constructor.

The application is responsible for providing the memory for the Ring Buffer. The argument ''numElements' is the number of items that will fit in the memory allocated by 'memoryForElements' - it is NOT the number of bytes of 'memoryForElements'.

Note: The maximum number of element that can actually be stored is numElements - 1 (one element/index/slot is consumed/used to represents the empty buffer state).

Member Function Documentation

add()

template<class ITEM >

bool Cpl::Container::RingBuffer< ITEM >::add ( const ITEM &  item )

inlinenoexcept

The contents of 'item' will be copied into the Ring Buffer as the 'last' item in the buffer.

Return true if the operation was successful; else false is returned, i.e. the Buffer was full prior to the attempted add().

addElements()

template<class ITEM >

void Cpl::Container::RingBuffer< ITEM >::addElements ( unsigned  numElementsAdded )

inlinenoexcept

This method 'adds' N elements - that were populated using the pointer returned from peekNextAddItems - to the ring buffer.

Basically its updates the tail pointer to reflect items added using direct memory access.

'numElementsAdded' be less than or equal to the 'dstNumFlatElements' returned from peekNextAddItems().

CAUTION: IF YOU DON'T UNDERSTAND THE USE CASE FOR THIS METHOD - THEN DON'T USE IT. If this method is used improperly, it WILL CORRUPT the Ring Buffer!

clearTheBuffer()

template<class ITEM >

void Cpl::Container::RingBuffer< ITEM >::clearTheBuffer ( )

inlinenoexcept

Empties the Ring Buffer.

All references to the item(s) in the buffer are lost.

getMaxItems()

template<class ITEM >

unsigned Cpl::Container::RingBuffer< ITEM >::getMaxItems ( void  ) const

inlinenoexcept

This method returns the maximum number of items that can be stored in the Ring buffer.

getNumItems()

template<class ITEM >

unsigned Cpl::Container::RingBuffer< ITEM >::getNumItems ( void  ) const

inlinenoexcept

This method returns the current number of items in the Ring Buffer.

isEmpty()

template<class ITEM >

bool Cpl::Container::RingBuffer< ITEM >::isEmpty ( void  ) const

inlinenoexcept

This method returns true if the Ring Buffer is empty.

isFull()

template<class ITEM >

bool Cpl::Container::RingBuffer< ITEM >::isFull ( void  ) const

inlinenoexcept

This method returns true if the Ring Buffer is full.

peekHead()

template<class ITEM >

ITEM * Cpl::Container::RingBuffer< ITEM >::peekHead ( void  ) const

inlinenoexcept

Returns a pointer to the first item in the Buffer.

The returned item remains in the buffer. Returns 0 if the Buffer is empty.

peekNextAddItems()

template<class ITEM >

ITEM * Cpl::Container::RingBuffer< ITEM >::peekNextAddItems ( unsigned &  dstNumFlatElements )

inlinenoexcept

This method returns a pointer to the next item to be added.

In addition it returns the number of elements that can be added as linear/flat buffer (i.e. without wrapping around raw buffer memory)

If the Ring buffer is full, a null pointer is returned

peekNextRemoveItems()

template<class ITEM >

ITEM * Cpl::Container::RingBuffer< ITEM >::peekNextRemoveItems ( unsigned &  dstNumFlatElements )

inlinenoexcept

This method returns a pointer to the next item to be removed.

In addition it returns the number of elements that can be removed as linear/flat buffer (i.e. without wrapping around raw buffer memory)

If the Ring buffer is empty, a null pointer is returned

peekTail()

template<class ITEM >

ITEM * Cpl::Container::RingBuffer< ITEM >::peekTail ( void  ) const

inlinenoexcept

Returns a pointer to the last item in the Buffer.

The returned item remains in the Buffer. Returns 0 if the Buffer is empty.

remove()

template<class ITEM >

bool Cpl::Container::RingBuffer< ITEM >::remove ( ITEM &  dst )

inlinenoexcept

Removes the first item in the Buffer.

The contents of the removed item will be copied into the 'dst' argument. The method return true if the operation was successful; else false is returned, i.e. the Ring buffer is/was empty.

removeElements()

template<class ITEM >

void Cpl::Container::RingBuffer< ITEM >::removeElements ( unsigned  numElementsToRemove )

inlinenoexcept

This method 'removes' N elements - that were removed using the pointer returned from peekNextRemoveItems - from the ring buffer.

Basically it updates the head pointer to reflect items removed using direct memory access.

'numElementsToRemove' be less than or equal to the 'dstNumFlatElements' returned from peekNextRemoveItems().

CAUTION: IF YOU DON'T UNDERSTAND THE USE CASE FOR THIS METHOD - THEN DON'T USE IT. If this method is used improperly, it WILL CORRUPT the Ring Buffer!

---

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

• Cpl/Container/RingBuffer.h