A data structure that allows appending at the back and invalidating from the front. More...

#include <Queue.hpp>

Classes
class	QueueIterator
	Class that alows queue elements to be accessed like a normal stl iterator. Queue iterator is a bidirectional sequential iterator isValid() method checks the validity of the iterator. This method can be used to check if the data in Queue has not yet been popped out Increment, decrement , dereferencing,less than and greater than operations are provided. More...

Public Types
using	value_type = DataT
	Typedef for the DataT.

using	QueueType = Queue< value_type >
	Typedef for the QueueType.

using	size_type = uint32_t

using	iterator = QueueIterator< false >
	Typedef for regular iterator.

using	const_iterator = QueueIterator< true >
	Typedef for constant iterator.

Public Member Functions
	Queue (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 queue.

	~Queue ()
	Destroy the Queue, clearing everything out.

	Queue (const Queue< value_type > &)=delete
	No copies, no moves.

Queue &	operator= (const Queue< value_type > &)=delete
	Deleting default assignment operator to prevent copies.

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.

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

value_type &	front () const
	Read and return the data at the front(oldest element), reference.

value_type &	back () const
	Read and return the last pushed in element(newest element), reference.

uint32_t	capacity () const
	Return the fixed size of this queue.

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

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

bool	empty () const
	Return if the queue is empty or not.

void	clear ()
	Empty the queue.

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

iterator	push (const value_type &dat)
	push data to the Queue.

iterator	push (value_type &&dat)
	push data to the Queue.

void	pop ()
	Pops the data at the front of the structure (oldest element) After pop iterator always points to the last element.

void	pop_back ()
	Pops the data at the back of the structure (newest element) After pop iterator always points to the last element.

iterator	begin ()
	STL-like begin operation, starts at front (oldest element)

iterator	end ()
	STL - like end operation, starts at element one past head.

const_iterator	begin () const
	STL-like begin operation, starts at front (oldest element)

const_iterator	end () const
	STL - like end operation, starts at element one past head.

Detailed Description

template<class DataT>
class sparta::Queue< DataT >

A data structure that allows appending at the back and invalidating from the front.

The Queue allows user to push data to the back of the queue and pop it from the front.

The queue does not manage any type of state delaying. In order to use the queue as a present state/next state queue, the user should use delays when writing to the queue's ports or listening to the queue's ports.

The only precedence that the Queue follows is that invalidations precede writes.

The queue can also be used without the port mechanism via public methods push and pop. The pop method is special in that it will return an iterator which points to that entry in Queue. At any time the queue entry can be queried for that data's location in the queue via its public getIndex() method.

Example usage

Queue<uint32_t> queue;
Queue<uint32_t>::iterator entry = queue.push(5);
Queue<uint32_t>::iterator entry2 = queue.push(52);
// where is the entry?
uint32_t = entry.getIndex();
assert(entry.getIndex() == 0);
assert(entry2.getIndex() == 1);
assert(queue.read(entry.getIndex() == 5));
 
// QueueIterator's respond to comparison operators. Their index is compared.
assert(entry < entry2);
 
 
queue.pop();
assert(entry2.getIndex() == 0);

Definition at line 69 of file Queue.hpp.

Member Typedef Documentation

◆ const_iterator

template<class DataT >

using sparta::Queue< DataT >::const_iterator = QueueIterator<true>

Typedef for constant iterator.

Definition at line 404 of file Queue.hpp.

◆ iterator

template<class DataT >

using sparta::Queue< DataT >::iterator = QueueIterator<false>

Typedef for regular iterator.

Definition at line 401 of file Queue.hpp.

◆ QueueType

template<class DataT >

using sparta::Queue< DataT >::QueueType = Queue<value_type>

Typedef for the QueueType.

Definition at line 77 of file Queue.hpp.

◆ size_type

template<class DataT >

using sparta::Queue< DataT >::size_type = uint32_t

Definition at line 80 of file Queue.hpp.

◆ value_type

template<class DataT >

using sparta::Queue< DataT >::value_type = DataT

Typedef for the DataT.

Definition at line 74 of file Queue.hpp.

Constructor & Destructor Documentation

◆ Queue()

template<class DataT >

sparta::Queue< DataT >::Queue	(	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`
	)

inline

Construct a queue.

Parameters

name	The name of the queue
num_entries	The number of entries this queue can hold
clk	The clock this queue belongs to
statset	The Counter set to register read-only counters; default nullptr
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 AUTO_VISIBILITY, for this structure AUTO_VISIBILITY 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 440 of file Queue.hpp.

◆ ~Queue()

template<class DataT >

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

inline

Destroy the Queue, clearing everything out.

Definition at line 473 of file Queue.hpp.

Here is the call graph for this function:

Member Function Documentation

◆ access()

template<class DataT >

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

inline

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

Parameters

idx	The index to read

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

Use the read() equivalent for const access

Definition at line 515 of file Queue.hpp.

Here is the call graph for this function:

◆ back()

template<class DataT >

value_type & sparta::Queue< DataT >::back ( ) const

inline

Read and return the last pushed in element(newest element), reference.

Returns: The data at the back (reference)

Definition at line 533 of file Queue.hpp.

Here is the call graph for this function:

◆ begin() [1/2]

template<class DataT >

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

inline

STL-like begin operation, starts at front (oldest element)

Returns: iterator to the oldest element in Queue

Definition at line 670 of file Queue.hpp.

Here is the call graph for this function:

◆ begin() [2/2]

template<class DataT >

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

inline

STL-like begin operation, starts at front (oldest element)

Returns: const_iterator to the oldest element in Queue

Definition at line 685 of file Queue.hpp.

Here is the call graph for this function:

◆ capacity()

template<class DataT >

uint32_t sparta::Queue< DataT >::capacity ( ) const

inline

Return the fixed size of this queue.

Returns: The size of this queue

Definition at line 544 of file Queue.hpp.

◆ clear()

template<class DataT >

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

inline

Empty the queue.

Removes all entries from the Queue

Definition at line 580 of file Queue.hpp.

◆ empty()

template<class DataT >

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

inline

Return if the queue is empty or not.

Returns: True, if the queue is empty

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

Definition at line 571 of file Queue.hpp.

◆ enableCollection()

template<class DataT >

void sparta::Queue< 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 603 of file Queue.hpp.

Here is the call graph for this function:

◆ end() [1/2]

template<class DataT >

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

inline

STL - like end operation, starts at element one past head.

Returns: Returns iterator pointing to past-the-end elemnt in Queue

Definition at line 681 of file Queue.hpp.

◆ end() [2/2]

template<class DataT >

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

inline

STL - like end operation, starts at element one past head.

Returns: Returns const_iterator pointing to past-the-end elemnt in Queue

Definition at line 696 of file Queue.hpp.

◆ front()

template<class DataT >

value_type & sparta::Queue< DataT >::front ( ) const

inline

Read and return the data at the front(oldest element), reference.

Returns: The data at the front (reference)

Definition at line 524 of file Queue.hpp.

Here is the call graph for this function:

◆ getName()

template<class DataT >

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

inline

Name of this resource.

Definition at line 484 of file Queue.hpp.

◆ isValid()

template<class DataT >

bool sparta::Queue< 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 494 of file Queue.hpp.

Here is the call graph for this function:

◆ numFree()

template<class DataT >

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

inline

Return the number of free entries.

Returns: The number of free entries

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

Definition at line 561 of file Queue.hpp.

Here is the call graph for this function:

◆ pop()

template<class DataT >

void sparta::Queue< DataT >::pop ( )

inline

Pops the data at the front of the structure (oldest element) After pop iterator always points to the last element.

Definition at line 636 of file Queue.hpp.

◆ pop_back()

template<class DataT >

void sparta::Queue< DataT >::pop_back ( )

inline

Pops the data at the back of the structure (newest element) After pop iterator always points to the last element.

Definition at line 654 of file Queue.hpp.

◆ push() [1/2]

template<class DataT >

iterator sparta::Queue< DataT >::push ( const value_type & dat )

inline

push data to the Queue.

Parameters

dat	Data to be copied in

Returns: a copy of a QueueIterator that can be queired at any time for this data's position in the queue.

Warning: appends through via this method are immediately valid.

Definition at line 615 of file Queue.hpp.

◆ push() [2/2]

template<class DataT >

iterator sparta::Queue< DataT >::push ( value_type && dat )

inline

push data to the Queue.

Parameters

dat	Data to be moved in

Returns: a copy of a QueueIterator that can be queired at any time for this data's position in the queue.

Warning: appends through via this method are immediately valid.

Definition at line 627 of file Queue.hpp.

◆ read()

template<class DataT >

const value_type & sparta::Queue< 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 503 of file Queue.hpp.

Here is the call graph for this function:

◆ size()

template<class DataT >

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

inline

Return the number of valid entries.

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

Definition at line 552 of file Queue.hpp.

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

/github/workspace/sparta/sparta/resources/Queue.hpp

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ iterator

◆ QueueType

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ Queue()

◆ ~Queue()

Member Function Documentation

◆ access()

◆ back()

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity()

◆ clear()

◆ empty()

◆ enableCollection()

◆ end() [1/2]

◆ end() [2/2]

◆ front()

◆ getName()

◆ isValid()

◆ numFree()

◆ pop()

◆ pop_back()

◆ push() [1/2]

◆ push() [2/2]

◆ read()

◆ size()