A data structure allowing appending at the end, beginning, or insert in the middle, but erase anywhere with collapse. More...

#include <CircularBuffer.hpp>

Public Types
typedef CircularBuffer< DataT >	CircularBufferType

typedef DataT	value_type

typedef uint32_t	size_type

typedef CircularBufferIterator< false >	iterator
	Typedef for regular iterator.

typedef CircularBufferIterator< true >	const_iterator
	Typedef for constant iterator.

typedef CircularBufferReverseIterator< const_iterator >	const_reverse_iterator
	Typedef for regular reverse iterator.

typedef CircularBufferReverseIterator< iterator >	reverse_iterator
	Typedef for constant reverse iterator.

Public Member Functions
	CircularBuffer (const std::string &name, const uint32_t max_size, const Clock clk, StatisticSet statset=nullptr, InstrumentationNode::visibility_t stat_vis_general=InstrumentationNode::AUTO_VISIBILITY, InstrumentationNode::visibility_t stat_vis_detailed=InstrumentationNode::VIS_HIDDEN, InstrumentationNode::visibility_t stat_vis_max=InstrumentationNode::AUTO_VISIBILITY, InstrumentationNode::visibility_t stat_vis_avg=InstrumentationNode::AUTO_VISIBILITY)
	Construct a CircularBuffer.

	CircularBuffer (const CircularBuffer< value_type > &)=delete
	No copies allowed for CircularBuffer.

CircularBuffer &	operator= (const CircularBuffer< value_type > &)=delete
	No copies, no moves allowed for CircularBuffer.

void	enableCollection (TreeNode *parent)
	Request that this queue begin collecting its contents for pipeline collection.

std::string	getName () const
	Get this CircularBuffer's name.

bool	isValid (uint32_t idx) const
	Determine if data at the index is valid.

size_type	capacity () const
	Return the fixed size of this CircularBuffer.

size_type	size () const
	Return the number of valid entries.

size_type	numFree () const
	Return the number of free entries.

void	push_back (const value_type &dat)
	Append data to the end of CircularBuffer, and return a CircularBufferIterator.

void	push_back (value_type &&dat)
	Append data to the end of CircularBuffer, and return a CircularBufferIterator.

iterator	insert (const iterator &entry, const value_type &dat)
	Insert the given data before the given iterator.

iterator	insert (const iterator &entry, value_type &&dat)
	Insert the given data before the given iterator.

iterator	insert (const const_iterator &entry, const value_type &dat)
	Insert the given data before the given iterator.

iterator	insert (const const_iterator &entry, value_type &&dat)
	Insert the given data before the given iterator.

void	erase (const_iterator entry)
	erase the index at which the entry exists in the CircularBuffer.

void	erase (const_reverse_iterator entry)
	erase the index at which the entry exists in the CircularBuffer.

void	erase (reverse_iterator entry)

void	clear ()
	Empty the contents of the CircularBuffer.

iterator	begin ()
	Get the iterator pointing to the oldest entry of CircularBuffer.

iterator	end ()
	Returns an iterator referring to past-the-end of the newest element in the CircularBuffer.

const_iterator	begin () const
	Get the iterator pointing to the oldest entry of CircularBuffer.

const_iterator	end () const
	Returns an iterator referring to past-the-end of the newest element in the CircularBuffer.

reverse_iterator	rbegin ()
	Get the iterator pointing to the oldest entry of CircularBuffer.

reverse_iterator	rend ()
	Returns an iterator referring to past-the-end of the newest element in the CircularBuffer.

const_reverse_iterator	rbegin () const
	Get the iterator pointing to the oldest entry of CircularBuffer.

const_reverse_iterator	rend () const
	Returns an iterator referring to past-the-end of the newest element in the CircularBuffer.

value_type	operator[] (const uint32_t idx)
	Returns the data at the given index. Will assert if out of range.

Detailed Description

template<class DataT>
class sparta::CircularBuffer< DataT >

A data structure allowing appending at the end, beginning, or insert in the middle, but erase anywhere with collapse.

The CircularBuffer allows a user to append data to the end or the beginning of the buffer, or insert into the middle of the CircularBuffer, and erase anywhere. The CircularBuffer will collapse on empty entries unlike the sparta::Array.

The CircularBuffer acks like a standard container via public push_back, insert, and erase methods. The CircularBufferIterator can be used as an index into the CircularBuffer, and maintains knowledge internally of its location in the CircularBuffer, as well whether or not it still represents a valid entry.

Where the CircularBuffer differs from the standard Buffer is that the CircularBuffer has no concept of "full", meaning it will wrap around and overwrite older entries. For example, if the CircularBuffer is 10 entries in size, the user can append to the CircularBuffer 11 times without error as the 11th append will simply overwrite the original first entry. Buffer, on the other hand, will assert.

Iterator behavior:

On push_back, existing iterators pointing to non-replaced values are still valid
A push_back that causes a "wrap-around" will invalidate those iterators pointing to older entries being replaced
erase will invalidate ALL iterators
insert will invalidate ALL iterators

Example:

CircularBuffer<uint32_t> circularbuffer;
circularbuffer.push_back(3);
circularbuffer.push_back(5);
circularbuffer.push_back(1);
 
sparta_assert(*(circularbuffer.begin()) == 3);
sparta_assert(*(circularbuffer.rbegin()) == 1);
 
auto it = circularbuffer.begin();
CircularBuffer.erase(it);
sparta_assert(!it.isValid());

Template Parameters

DataT The data type contained in the CircularBuffer.

Definition at line 85 of file CircularBuffer.hpp.

Member Typedef Documentation

◆ CircularBufferType

template<class DataT >

typedef CircularBuffer<DataT> sparta::CircularBuffer< DataT >::CircularBufferType

Definition at line 91 of file CircularBuffer.hpp.

◆ const_iterator

template<class DataT >

typedef CircularBufferIterator<true> sparta::CircularBuffer< DataT >::const_iterator

Typedef for constant iterator.

Definition at line 376 of file CircularBuffer.hpp.

◆ const_reverse_iterator

template<class DataT >

typedef CircularBufferReverseIterator<const_iterator> sparta::CircularBuffer< DataT >::const_reverse_iterator

Typedef for regular reverse iterator.

Definition at line 379 of file CircularBuffer.hpp.

◆ iterator

template<class DataT >

typedef CircularBufferIterator<false> sparta::CircularBuffer< DataT >::iterator

Typedef for regular iterator.

Definition at line 373 of file CircularBuffer.hpp.

◆ reverse_iterator

template<class DataT >

typedef CircularBufferReverseIterator<iterator> sparta::CircularBuffer< DataT >::reverse_iterator

Typedef for constant reverse iterator.

Definition at line 382 of file CircularBuffer.hpp.

◆ size_type

template<class DataT >

typedef uint32_t sparta::CircularBuffer< DataT >::size_type

Definition at line 97 of file CircularBuffer.hpp.

◆ value_type

template<class DataT >

typedef DataT sparta::CircularBuffer< DataT >::value_type

Definition at line 94 of file CircularBuffer.hpp.

Constructor & Destructor Documentation

◆ CircularBuffer()

template<class DataT >

sparta::CircularBuffer< DataT >::CircularBuffer	(	const std::string &	name,
		const uint32_t	max_size,
		const Clock *	clk,
		StatisticSet *	statset = `nullptr`,
		InstrumentationNode::visibility_t	stat_vis_general = `InstrumentationNode::AUTO_VISIBILITY`,
		InstrumentationNode::visibility_t	stat_vis_detailed = `InstrumentationNode::VIS_HIDDEN`,
		InstrumentationNode::visibility_t	stat_vis_max = `InstrumentationNode::AUTO_VISIBILITY`,
		InstrumentationNode::visibility_t	stat_vis_avg = `InstrumentationNode::AUTO_VISIBILITY`
	)

Construct a CircularBuffer.

Parameters

name	The name of the CircularBuffer
max_size	The number of entries this CircularBuffer can hold before wrapping
clk	The clock this CircularBuffer is associated with – used for CycleCounter
statset	Pointer to the counter set to register utilization counts; default nullptr. This works for timed and untimed.
stat_vis_general	Sets the visibility of the stat counters for the 0th and last index of the utilization counts, so the empty and full counts.
stat_vis_detailed	Sets the visibility of the stat counts between 0 and the last index. i.e. more detailed than the general stats, default VIS_HIDDEN
stat_vis_max	Sets the visibility for a stat that contains the maximum utilization for this buffer. The default is AUTO_VISIBILITY.
stat_vis_avg	Sets the visibility for a stat that contains the weighted utilization average for this buffer. The default is AUTO_VISIBILITY.

Warning: By default the stat_vis_* options are set to VIS_SPARTA_DEFAULT, for this structure VIS_SPARTA_DEFAULT resolves to SPARTA_CONTAINER_DEFAULT which at the time of writing this comment is set to VIS_HIDDEN. If you rely on the stats from this container you should explicity set the visibility.

Definition at line 797 of file CircularBuffer.hpp.

Member Function Documentation

◆ begin() [1/2]

template<class DataT >

iterator sparta::CircularBuffer< DataT >::begin ( )

inline

Get the iterator pointing to the oldest entry of CircularBuffer.

Returns: Iterator pointing to oldest element in CircularBuffer

Definition at line 602 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ begin() [2/2]

template<class DataT >

const_iterator sparta::CircularBuffer< DataT >::begin ( ) const

inline

Get the iterator pointing to the oldest entry of CircularBuffer.

Returns: Iterator pointing to oldest element in CircularBuffer

Definition at line 625 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ capacity()

template<class DataT >

size_type sparta::CircularBuffer< DataT >::capacity ( ) const

inline

Return the fixed size of this CircularBuffer.

Returns: The size of this CircularBuffer

Definition at line 469 of file CircularBuffer.hpp.

◆ clear()

template<class DataT >

void sparta::CircularBuffer< DataT >::clear ( )

inline

Empty the contents of the CircularBuffer.

Definition at line 588 of file CircularBuffer.hpp.

◆ enableCollection()

template<class DataT >

void sparta::CircularBuffer< DataT >::enableCollection ( TreeNode * parent )

inline

Request that this queue begin collecting its contents for pipeline collection.

Parameters

parent A pointer to the parent treenode for which to add Collectable objects under.

Note: This only sets the Queue up for collection. collection must be started with an instatiation of the PipelineCollector

Definition at line 444 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ end() [1/2]

template<class DataT >

iterator sparta::CircularBuffer< DataT >::end ( )

inline

Returns an iterator referring to past-the-end of the newest element in the CircularBuffer.

Definition at line 615 of file CircularBuffer.hpp.

◆ end() [2/2]

template<class DataT >

const_iterator sparta::CircularBuffer< DataT >::end ( ) const

inline

Returns an iterator referring to past-the-end of the newest element in the CircularBuffer.

Definition at line 638 of file CircularBuffer.hpp.

◆ erase() [1/3]

template<class DataT >

void sparta::CircularBuffer< DataT >::erase ( const_iterator entry )

inline

erase the index at which the entry exists in the CircularBuffer.

Parameters

entry a reference to the entry to be erased.

Definition at line 563 of file CircularBuffer.hpp.

◆ erase() [2/3]

template<class DataT >

void sparta::CircularBuffer< DataT >::erase ( const_reverse_iterator entry )

inline

erase the index at which the entry exists in the CircularBuffer.

Parameters

entry a reference to the entry to be erased.

Definition at line 574 of file CircularBuffer.hpp.

◆ erase() [3/3]

template<class DataT >

void sparta::CircularBuffer< DataT >::erase ( reverse_iterator entry )

inline

Definition at line 580 of file CircularBuffer.hpp.

◆ getName()

template<class DataT >

std::string sparta::CircularBuffer< DataT >::getName ( ) const

inline

Get this CircularBuffer's name.

Definition at line 451 of file CircularBuffer.hpp.

◆ insert() [1/4]

template<class DataT >

iterator sparta::CircularBuffer< DataT >::insert	(	const const_iterator &	entry,
		const value_type &	dat
	)

inline

Insert the given data before the given iterator.

Parameters

entry	The interator to insert the data before
dat	The data to insert

Definition at line 544 of file CircularBuffer.hpp.

◆ insert() [2/4]

template<class DataT >

iterator sparta::CircularBuffer< DataT >::insert	(	const const_iterator &	entry,
		value_type &&	dat
	)

inline

Insert the given data before the given iterator.

Parameters

entry	The interator to insert the data before
dat	The data to insert

Definition at line 554 of file CircularBuffer.hpp.

◆ insert() [3/4]

template<class DataT >

iterator sparta::CircularBuffer< DataT >::insert	(	const iterator &	entry,
		const value_type &	dat
	)

inline

Insert the given data before the given iterator.

Parameters

entry	The interator to insert the data before
dat	The data to insert

Definition at line 524 of file CircularBuffer.hpp.

◆ insert() [4/4]

template<class DataT >

iterator sparta::CircularBuffer< DataT >::insert	(	const iterator &	entry,
		value_type &&	dat
	)

inline

Insert the given data before the given iterator.

Parameters

entry	The interator to insert the data before
dat	The data to insert

Definition at line 534 of file CircularBuffer.hpp.

◆ isValid()

template<class DataT >

bool sparta::CircularBuffer< DataT >::isValid ( uint32_t idx ) const

inline

Determine if data at the index is valid.

Parameters

idx	The index to determine validity

Returns: true if valid; false otherwise

Definition at line 461 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ numFree()

template<class DataT >

size_type sparta::CircularBuffer< DataT >::numFree ( ) const

inline

Return the number of free entries.

Returns: The number of free entries

Does not take into account the number of erased entries this cycle

Definition at line 487 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ operator[]()

template<class DataT >

value_type sparta::CircularBuffer< DataT >::operator[] ( const uint32_t idx )

inline

Returns the data at the given index. Will assert if out of range.

Note: This method is not const due to a bug in GCC. See the data type in CircularBufferIterator

Definition at line 681 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ push_back() [1/2]

template<class DataT >

void sparta::CircularBuffer< DataT >::push_back ( const value_type & dat )

inline

Append data to the end of CircularBuffer, and return a CircularBufferIterator.

Parameters

dat	Data to be pushed back into the CircularBuffer

Returns: a CircularBufferIterator created to represent the object appended.

Append data to the end of CircularBuffer, and return a CircularBufferIterator for the location appeneded. Untimed CircularBuffers will have the data become valid immediately.

Definition at line 500 of file CircularBuffer.hpp.

◆ push_back() [2/2]

template<class DataT >

void sparta::CircularBuffer< DataT >::push_back ( value_type && dat )

inline

Append data to the end of CircularBuffer, and return a CircularBufferIterator.

Parameters

dat	Data to be pushed back into the CircularBuffer

Returns: a CircularBufferIterator created to represent the object appended.

Append data to the end of CircularBuffer, and return a CircularBufferIterator for the location appeneded. Untimed CircularBuffers will have the data become valid immediately.

Definition at line 514 of file CircularBuffer.hpp.

◆ rbegin() [1/2]

template<class DataT >

reverse_iterator sparta::CircularBuffer< DataT >::rbegin ( )

inline

Get the iterator pointing to the oldest entry of CircularBuffer.

Returns: Iterator pointing to oldest element in CircularBuffer

Definition at line 648 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ rbegin() [2/2]

template<class DataT >

const_reverse_iterator sparta::CircularBuffer< DataT >::rbegin ( ) const

inline

Get the iterator pointing to the oldest entry of CircularBuffer.

Returns: Iterator pointing to oldest element in CircularBuffer

Definition at line 664 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ rend() [1/2]

template<class DataT >

reverse_iterator sparta::CircularBuffer< DataT >::rend ( )

inline

Returns an iterator referring to past-the-end of the newest element in the CircularBuffer.

Definition at line 656 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ rend() [2/2]

template<class DataT >

const_reverse_iterator sparta::CircularBuffer< DataT >::rend ( ) const

inline

Returns an iterator referring to past-the-end of the newest element in the CircularBuffer.

Definition at line 672 of file CircularBuffer.hpp.

Here is the call graph for this function:

◆ size()

template<class DataT >

size_type sparta::CircularBuffer< DataT >::size ( ) const

inline

Return the number of valid entries.

Returns: The number of valid entries. Does not subtract entries erased this cycle

Definition at line 477 of file CircularBuffer.hpp.

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

/github/workspace/sparta/sparta/resources/CircularBuffer.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ CircularBufferType

◆ const_iterator

◆ const_reverse_iterator

◆ iterator

◆ reverse_iterator

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ CircularBuffer()

Member Function Documentation

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity()

◆ clear()

◆ enableCollection()

◆ end() [1/2]

◆ end() [2/2]

◆ erase() [1/3]

◆ erase() [2/3]

◆ erase() [3/3]

◆ getName()

◆ insert() [1/4]

◆ insert() [2/4]

◆ insert() [3/4]

◆ insert() [4/4]

◆ isValid()

◆ numFree()

◆ operator[]()

◆ push_back() [1/2]

◆ push_back() [2/2]

◆ rbegin() [1/2]

◆ rbegin() [2/2]

◆ rend() [1/2]

◆ rend() [2/2]

◆ size()