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

Detailed Description

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

This template class implements a THREAD SAFE Ring Buffer.

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

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

#include <RingBufferMT.h>

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

[legend]

Collaboration diagram for Cpl::Container::RingBufferMT< ITEM >:

[legend]

Public Member Functions
	RingBufferMT (unsigned maxElements, ITEM memoryForElements[]) noexcept
	Constructor.

bool	remove (ITEM &dst) noexcept
	See Cpl::Container::RingBuffer.

bool	add (const ITEM &item) noexcept
	See Cpl::Container::RingBuffer.

ITEM *	peekHead (void) const noexcept
	See Cpl::Container::RingBuffer.

ITEM *	peekTail (void) const noexcept
	See Cpl::Container::RingBuffer.

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.

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.

bool	isEmpty (void) const noexcept
	See Cpl::Container::RingBuffer.

bool	isFull (void) const noexcept
	See Cpl::Container::RingBuffer.

unsigned	getNumItems (void) const noexcept
	See Cpl::Container::RingBuffer.

unsigned	getMaxItems (void) const noexcept
	See Cpl::Container::RingBuffer.

void	clearTheBuffer () noexcept
	See Cpl::Container::RingBuffer.

Public Member Functions inherited from Cpl::Container::RingBuffer< ITEM >
	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.

Protected Attributes
Cpl::System::Mutex	m_lock
	Mutex for critical sections.

Constructor & Destructor Documentation

◆ RingBufferMT()

template<class ITEM >

Cpl::Container::RingBufferMT< ITEM >::RingBufferMT	(	unsigned	maxElements,
		ITEM	memoryForElements[]
	)

inlinenoexcept

Constructor.

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

Member Function Documentation

◆ add()

template<class ITEM >

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

inlinenoexcept

See Cpl::Container::RingBuffer.

◆ addElements()

template<class ITEM >

void Cpl::Container::RingBufferMT< 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(). If the call to peekNextAddTiems, THEN 'numElementsAdded' MUST BE SET to zero.

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!
MUST ALWAYS BE CALLED following a call to peekNextAddItems().

◆ clearTheBuffer()

template<class ITEM >

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

inlinenoexcept

See Cpl::Container::RingBuffer.

◆ getMaxItems()

template<class ITEM >

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

inlinenoexcept

See Cpl::Container::RingBuffer.

◆ getNumItems()

template<class ITEM >

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

inlinenoexcept

See Cpl::Container::RingBuffer.

◆ isEmpty()

template<class ITEM >

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

inlinenoexcept

See Cpl::Container::RingBuffer.

◆ isFull()

template<class ITEM >

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

inlinenoexcept

See Cpl::Container::RingBuffer.

◆ peekHead()

template<class ITEM >

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

inlinenoexcept

See Cpl::Container::RingBuffer.

◆ peekNextAddItems()

template<class ITEM >

ITEM * Cpl::Container::RingBufferMT< 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 (and 'dstNumFlatElements' is set to zero).

This method with addElements() method provide an ATOMIC update of the ring buffer. This means that addElements() MUST ALWAYS be called after calling peekNextAddItems().

◆ peekNextRemoveItems()

template<class ITEM >

ITEM * Cpl::Container::RingBufferMT< 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 (and 'dstNumFlatElements' is set to zero).

This method with removeElements() method provide an ATOMIC update of the ring buffer. This means that removeElements() MUST ALWAYS be called after calling peekNextRemoveItems().

◆ peekTail()

template<class ITEM >

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

inlinenoexcept

See Cpl::Container::RingBuffer.

◆ remove()

template<class ITEM >

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

inlinenoexcept

See Cpl::Container::RingBuffer.

◆ removeElements()

template<class ITEM >

void Cpl::Container::RingBufferMT< 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!
MUST ALWAYS BE CALLED following a call to peekNextRemoveItems().

Member Data Documentation

◆ m_lock

template<class ITEM >

Cpl::System::Mutex Cpl::Container::RingBufferMT< ITEM >::m_lock

protected

Mutex for critical sections.

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

Cpl/Container/RingBufferMT.h

Detailed Description

Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ RingBufferMT()

Member Function Documentation

◆ add()

◆ addElements()

◆ clearTheBuffer()

◆ getMaxItems()

◆ getNumItems()

◆ isEmpty()

◆ isFull()

◆ peekHead()

◆ peekNextAddItems()

◆ peekNextRemoveItems()

◆ peekTail()

◆ remove()

◆ removeElements()

Member Data Documentation

◆ m_lock