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

#include <Buffer.hpp>

Public Types
typedef Buffer< DataT >	BufferType

typedef DataT	value_type

typedef uint32_t	size_type

typedef BufferIterator< false >	iterator
	Typedef for regular iterator.

typedef BufferIterator< true >	const_iterator
	Typedef for constant iterator.

typedef std::reverse_iterator< const_iterator >	const_reverse_iterator
	Typedef for regular reverse iterator.

typedef std::reverse_iterator< iterator >	reverse_iterator
	Typedef for constant reverse iterator.

Public Member Functions
	Buffer (const std::string &name, const uint32_t num_entries, 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 buffer.

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

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

	Buffer (Buffer< value_type > &&)
	Move Constructor to allow moves.

	~Buffer ()
	Clear (and destruct the Buffer's contents)

const std::string &	getName () const
	Name of this resource.

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

const value_type &	read (uint32_t idx) const
	Read and return the data at the given index, const reference.

const value_type &	read (const const_iterator &entry) const
	read the entry at the BufferIterator's location

const value_type &	read (const const_reverse_iterator &entry) const
	read the entry at the BufferIterator's location

value_type &	access (uint32_t idx)
	Read and return the data at the given index, reference.

value_type &	access (const const_iterator &entry)
	Read and return the data at the given BufferIterator's location, reference.

value_type &	access (const const_reverse_iterator &entry)
	Read and return the data at the given BufferIterator's location, reference.

value_type &	accessBack ()
	Read and return the data at the bottom of the Buffer.

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

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

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

iterator	push_back (const value_type &dat)
	Append data to the end of Buffer, and return a BufferIterator.

iterator	push_back (value_type &&dat)
	Append data to the end of Buffer, and return a BufferIterator.

iterator	insert (uint32_t idx, const value_type &dat)
	Insert the item BEFORE the given index.

iterator	insert (uint32_t idx, value_type &&dat)
	Insert the item BEFORE the given index.

iterator	insert (const const_iterator &entry, const value_type &dat)
	Do an insert before a BufferIterator see insert method above.

iterator	insert (const const_iterator &entry, value_type &&dat)
	Do an insert before a BufferIterator see insert method above.

iterator	insert (const const_reverse_iterator &entry, const value_type &dat)
	Do an insert before a BufferIterator see insert method above.

iterator	insert (const const_reverse_iterator &entry, value_type &&dat)
	Do an insert before a BufferIterator see insert method above.

void	erase (const uint32_t &idx)
	erase a position in the Buffer immediately.

void	erase (const const_iterator &entry)
	erase the index at which the entry exists in the Buffer.

void	erase (const const_reverse_iterator &entry)
	erase the index at which the entry exists in the Buffer.

void	clear ()
	Empty the contents of the Buffer.

bool	empty () const
	Query if the buffer is empty.

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

iterator	begin ()
	Get the iterator pointing to the beginning of Buffer.

iterator	end ()
	Returns an iterator referring to past-the-end element in the Buffer container.

const_iterator	begin () const
	Get the const_iterator pointing to the begin of Buffer.

const_iterator	end () const
	Returns a const_iterator referring to past-the-end element in the Buffer container.

reverse_iterator	rbegin ()
	Get the iterator pointing to the pass-the-end element of Buffer.

reverse_iterator	rend ()
	Returns an reverse iterator referring to starting element in the Buffer container.

const_reverse_iterator	rbegin () const
	Get the const_reverse_iterator pointing to the pass-the-end of Buffer.

const_reverse_iterator	rend () const
	Returns a const_reverse_iterator referring to start element in the Buffer container.

void	makeInfinite (const uint32_t resize_delta=1)
	Makes the Buffer grow beyond its capacity. The buffer grows by adding new entries in its internal vectors. The number of new entries it adds defaults to the value 1, each time it resizes itself.

Detailed Description

template<class DataT>
class sparta::Buffer< DataT >

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

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

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

Warning: Once an entry has been appended with appendEntry method, the index with that data can only be erased via the erase(BufferIterator&), and not the erase(uint32_t).

Example:

Buffer<uint32_t> buffer;
Buffer<uint32_t>::iterator entry = buffer.push_back(3);
Buffer<uint32_t>::iterator entry2 = buffer.push_back(5);
buffer.push_back(1);
 
assert(buffer.read(2) == 1);
 
buffer.erase(1);
buffer.erase(entry2); // THROWS an exception since the location that entry2 represented.
// was erased.
 
Buffer<uint32_t>::BufferIterator e_copy(entry);
buffer.erase(e_copy);
// THROWS expection b/c the data represented by e_copy and entry
// are invalid after the line above
buffer.erase(entry);

Template Parameters

DataT The data type contained in the Buffer

Definition at line 73 of file Buffer.hpp.

Member Typedef Documentation

◆ BufferType

template<class DataT >

typedef Buffer<DataT> sparta::Buffer< DataT >::BufferType

Definition at line 79 of file Buffer.hpp.

◆ const_iterator

template<class DataT >

typedef BufferIterator<true> sparta::Buffer< DataT >::const_iterator

Typedef for constant iterator.

Definition at line 333 of file Buffer.hpp.

◆ const_reverse_iterator

template<class DataT >

typedef std::reverse_iterator<const_iterator> sparta::Buffer< DataT >::const_reverse_iterator

Typedef for regular reverse iterator.

Definition at line 336 of file Buffer.hpp.

◆ iterator

template<class DataT >

typedef BufferIterator<false> sparta::Buffer< DataT >::iterator

Typedef for regular iterator.

Definition at line 330 of file Buffer.hpp.

◆ reverse_iterator

template<class DataT >

typedef std::reverse_iterator<iterator> sparta::Buffer< DataT >::reverse_iterator

Typedef for constant reverse iterator.

Definition at line 339 of file Buffer.hpp.

◆ size_type

template<class DataT >

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

Definition at line 85 of file Buffer.hpp.

◆ value_type

template<class DataT >

typedef DataT sparta::Buffer< DataT >::value_type

Definition at line 82 of file Buffer.hpp.

Constructor & Destructor Documentation

◆ Buffer() [1/2]

template<class DataT >

sparta::Buffer< DataT >::Buffer	(	const std::string &	name,
		const uint32_t	num_entries,
		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 buffer.

Parameters

name	The name of the buffer
num_entries	The number of entries this buffer can hold
clk	The clock this Buffer is associated; used for internal counters
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 1034 of file Buffer.hpp.

Here is the call graph for this function:

◆ Buffer() [2/2]

template<typename DataT >

sparta::Buffer< DataT >::Buffer ( Buffer< value_type > && rval )

Move Constructor to allow moves.

Definition at line 1069 of file Buffer.hpp.

◆ ~Buffer()

template<class DataT >

sparta::Buffer< DataT >::~Buffer ( )

inline

Clear (and destruct the Buffer's contents)

Definition at line 397 of file Buffer.hpp.

Here is the call graph for this function:

Member Function Documentation

◆ access() [1/3]

template<class DataT >

value_type & sparta::Buffer< DataT >::access ( const const_iterator & entry )

inline

Read and return the data at the given BufferIterator's location, reference.

Parameters

entry the BufferIterator to read from.

Definition at line 459 of file Buffer.hpp.

Here is the call graph for this function:

◆ access() [2/3]

template<class DataT >

value_type & sparta::Buffer< DataT >::access ( const const_reverse_iterator & entry )

inline

Read and return the data at the given BufferIterator's location, reference.

Parameters

entry the BufferIterator to read from.

Definition at line 467 of file Buffer.hpp.

Here is the call graph for this function:

◆ access() [3/3]

template<class DataT >

value_type & sparta::Buffer< DataT >::access ( uint32_t idx )

inline

Read and return the data at the given index, reference.

Parameters

idx	The index to read

Returns: The data to return at the given index (reference) logarithmic time complexity on average

Definition at line 450 of file Buffer.hpp.

Here is the call graph for this function:

◆ accessBack()

template<class DataT >

value_type & sparta::Buffer< DataT >::accessBack ( )

inline

Read and return the data at the bottom of the Buffer.

Returns: The data to return at the given index (reference) logarithmic time complexity on average

Definition at line 476 of file Buffer.hpp.

Here is the call graph for this function:

◆ begin() [1/2]

template<class DataT >

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

inline

Get the iterator pointing to the beginning of Buffer.

Returns: Iterator pointing to first element in buffer

Definition at line 739 of file Buffer.hpp.

◆ begin() [2/2]

template<class DataT >

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

inline

Get the const_iterator pointing to the begin of Buffer.

Returns: const_iterator pointing to first element in buffer

Definition at line 757 of file Buffer.hpp.

◆ capacity()

template<class DataT >

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

inline

Return the fixed size of this buffer.

Returns: The size of this buffer

Definition at line 485 of file Buffer.hpp.

◆ clear()

template<class DataT >

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

inline

Empty the contents of the Buffer.

Definition at line 689 of file Buffer.hpp.

◆ empty()

template<class DataT >

bool sparta::Buffer< DataT >::empty ( ) const

inline

Query if the buffer is empty.

Definition at line 715 of file Buffer.hpp.

◆ enableCollection()

template<class DataT >

void sparta::Buffer< 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 729 of file Buffer.hpp.

◆ end() [1/2]

template<class DataT >

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

inline

Returns an iterator referring to past-the-end element in the Buffer container.

Definition at line 751 of file Buffer.hpp.

◆ end() [2/2]

template<class DataT >

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

inline

Returns a const_iterator referring to past-the-end element in the Buffer container.

Definition at line 768 of file Buffer.hpp.

◆ erase() [1/3]

template<class DataT >

void sparta::Buffer< DataT >::erase ( const const_iterator & entry )

inline

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

Parameters

entry a reference to the entry to be erased.

Definition at line 667 of file Buffer.hpp.

Here is the call graph for this function:

◆ erase() [2/3]

template<class DataT >

void sparta::Buffer< DataT >::erase ( const const_reverse_iterator & entry )

inline

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

Parameters

entry a reference to the entry to be erased.

Definition at line 678 of file Buffer.hpp.

Here is the call graph for this function:

◆ erase() [3/3]

template<class DataT >

void sparta::Buffer< DataT >::erase ( const uint32_t & idx )

inline

erase a position in the Buffer immediately.

Parameters

idx	the index to be erased.

In a un-TimedBuffer, invalidations immediately changes the indexes in the buffer using this function. Therefore, it's recommended that erases are performed using a BufferIterator.

Warning: This method will throw an exception if the index can be represented by an existing BufferIterator. If a BufferIterator has been created, the erase(BufferIterator&) should be used.

Definition at line 619 of file Buffer.hpp.

Here is the call graph for this function:

◆ getName()

template<class DataT >

const std::string & sparta::Buffer< DataT >::getName ( ) const

inline

Name of this resource.

Definition at line 402 of file Buffer.hpp.

◆ insert() [1/6]

template<class DataT >

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

inline

Do an insert before a BufferIterator see insert method above.

Definition at line 582 of file Buffer.hpp.

Here is the call graph for this function:

◆ insert() [2/6]

template<class DataT >

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

inline

Do an insert before a BufferIterator see insert method above.

Definition at line 588 of file Buffer.hpp.

Here is the call graph for this function:

◆ insert() [3/6]

template<class DataT >

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

inline

Do an insert before a BufferIterator see insert method above.

Definition at line 594 of file Buffer.hpp.

Here is the call graph for this function:

◆ insert() [4/6]

template<class DataT >

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

inline

Do an insert before a BufferIterator see insert method above.

Definition at line 600 of file Buffer.hpp.

Here is the call graph for this function:

◆ insert() [5/6]

template<class DataT >

iterator sparta::Buffer< DataT >::insert	(	uint32_t	idx,
		const value_type &	dat
	)

inline

Insert the item BEFORE the given index.

Parameters

idx	The index to insert the new item before
dat	The data to insert

Returns: A BufferIterator for the new location.

As an example, if the buffer contains:

[a, b, c]

an insert(1, w) becomes

[a, w, b, c]

Definition at line 553 of file Buffer.hpp.

◆ insert() [6/6]

template<class DataT >

iterator sparta::Buffer< DataT >::insert	(	uint32_t	idx,
		value_type &&	dat
	)

inline

Insert the item BEFORE the given index.

Parameters

idx	The index to insert the new item before
dat	The data to insert

Returns: A BufferIterator for the new location.

As an example, if the buffer contains:

[a, b, c]

an insert(1, w) becomes

[a, w, b, c]

Definition at line 576 of file Buffer.hpp.

◆ isValid()

template<class DataT >

bool sparta::Buffer< 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 412 of file Buffer.hpp.

Here is the call graph for this function:

◆ makeInfinite()

template<class DataT >

void sparta::Buffer< DataT >::makeInfinite ( const uint32_t resize_delta = 1 )

inline

Makes the Buffer grow beyond its capacity. The buffer grows by adding new entries in its internal vectors. The number of new entries it adds defaults to the value 1, each time it resizes itself.

Definition at line 804 of file Buffer.hpp.

◆ numFree()

template<class DataT >

size_type sparta::Buffer< 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 503 of file Buffer.hpp.

Here is the call graph for this function:

◆ push_back() [1/2]

template<class DataT >

iterator sparta::Buffer< DataT >::push_back ( const value_type & dat )

inline

Append data to the end of Buffer, and return a BufferIterator.

Parameters

dat	Data to be pushed back into the buffer

Returns: a BufferIterator created to represent the object appended.

Append data to the end of Buffer, and return a BufferIterator for the location appeneded. Untimed Buffers will have the data become valid immediately.

Definition at line 516 of file Buffer.hpp.

◆ push_back() [2/2]

template<class DataT >

iterator sparta::Buffer< DataT >::push_back ( value_type && dat )

inline

Append data to the end of Buffer, and return a BufferIterator.

Parameters

dat	Data to be pushed back into the buffer

Returns: a BufferIterator created to represent the object appended.

Append data to the end of Buffer, and return a BufferIterator for the location appeneded. Untimed Buffers will have the data become valid immediately.

Definition at line 530 of file Buffer.hpp.

◆ rbegin() [1/2]

template<class DataT >

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

inline

Get the iterator pointing to the pass-the-end element of Buffer.

Returns: Revese iterator pointing to last element in buffer

Definition at line 774 of file Buffer.hpp.

◆ rbegin() [2/2]

template<class DataT >

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

inline

Get the const_reverse_iterator pointing to the pass-the-end of Buffer.

Returns: const_reverse_iterator pointing to first element in buffer

Definition at line 788 of file Buffer.hpp.

◆ read() [1/3]

template<class DataT >

const value_type & sparta::Buffer< DataT >::read ( const const_iterator & entry ) const

inline

read the entry at the BufferIterator's location

Parameters

entry the BufferIterator to read from.

Definition at line 430 of file Buffer.hpp.

Here is the call graph for this function:

◆ read() [2/3]

template<class DataT >

const value_type & sparta::Buffer< DataT >::read ( const const_reverse_iterator & entry ) const

inline

read the entry at the BufferIterator's location

Parameters

entry the BufferIterator to read from.

Definition at line 439 of file Buffer.hpp.

Here is the call graph for this function:

◆ read() [3/3]

template<class DataT >

const value_type & sparta::Buffer< DataT >::read ( uint32_t idx ) const

inline

Read and return the data at the given index, const reference.

Parameters

idx	The index to read

Returns: The data to return at the given index (const reference)

Definition at line 421 of file Buffer.hpp.

Here is the call graph for this function:

◆ rend() [1/2]

template<class DataT >

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

inline

Returns an reverse iterator referring to starting element in the Buffer container.

Definition at line 782 of file Buffer.hpp.

◆ rend() [2/2]

template<class DataT >

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

inline

Returns a const_reverse_iterator referring to start element in the Buffer container.

Definition at line 796 of file Buffer.hpp.

◆ size()

template<class DataT >

size_type sparta::Buffer< 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 493 of file Buffer.hpp.

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

/github/workspace/sparta/sparta/resources/Buffer.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ BufferType

◆ const_iterator

◆ const_reverse_iterator

◆ iterator

◆ reverse_iterator

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ Buffer() [1/2]

◆ Buffer() [2/2]

◆ ~Buffer()

Member Function Documentation

◆ access() [1/3]

◆ access() [2/3]

◆ access() [3/3]

◆ accessBack()

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity()

◆ clear()

◆ empty()

◆ enableCollection()

◆ end() [1/2]

◆ end() [2/2]

◆ erase() [1/3]

◆ erase() [2/3]

◆ erase() [3/3]

◆ getName()

◆ insert() [1/6]

◆ insert() [2/6]

◆ insert() [3/6]

◆ insert() [4/6]

◆ insert() [5/6]

◆ insert() [6/6]

◆ isValid()

◆ makeInfinite()

◆ numFree()

◆ push_back() [1/2]

◆ push_back() [2/2]

◆ rbegin() [1/2]

◆ rbegin() [2/2]

◆ read() [1/3]

◆ read() [2/3]

◆ read() [3/3]

◆ rend() [1/2]

◆ rend() [2/2]

◆ size()