Hoa Nguyen has uploaded this change for review. (
https://gem5-review.googlesource.com/c/public/gem5/+/32962 )
Change subject: base: Tag API methods and variables to circular_queue.hh
......................................................................
base: Tag API methods and variables to circular_queue.hh
Change-Id: I0e6a89a3e3d14a6d269277e1ffeea1ed49d8e1e4
Signed-off-by: Hoa Nguyen <hoangu...@ucdavis.edu>
---
M src/base/circular_queue.hh
1 file changed, 194 insertions(+), 25 deletions(-)
diff --git a/src/base/circular_queue.hh b/src/base/circular_queue.hh
index b2d4cb5..78cf76e 100644
--- a/src/base/circular_queue.hh
+++ b/src/base/circular_queue.hh
@@ -154,6 +154,9 @@
uint32_t _round;
public:
+ /**
+ * @ingroup api_circular_queue
+ */
iterator(CircularQueue* cq, uint32_t idx, uint32_t round)
: _cq(cq), _idx(idx), _round(round) {}
@@ -172,11 +175,20 @@
static_assert(std::is_same<reference, T&>::value,
"reference type is not assignable as required");
+ /**
+ * @ingroup api_circular_queue
+ */
iterator() : _cq(nullptr), _idx(0), _round(0) { }
+ /**
+ * @ingroup api_circular_queue
+ */
iterator(const iterator& it)
: _cq(it._cq), _idx(it._idx), _round(it._round) {}
+ /**
+ * @ingroup api_circular_queue
+ */
iterator&
operator=(const iterator& it)
{
@@ -186,9 +198,13 @@
return *this;
}
+ /**
+ * @ingroup api_circular_queue
+ */
~iterator() { _cq = nullptr; _idx = 0; _round = 0; }
- /** Test dereferenceability.
+ /**
+ * Test dereferenceability.
* An iterator is dereferenceable if it is pointing to a non-null
* circular queue, it is not the past-the-end iterator and the
* index is a valid index to that queue. PTE test is required to
@@ -200,6 +216,8 @@
* Sometimes, though, users will get the PTE iterator and expect it
* to work after growing the buffer on the tail, so we have to
* check if the iterator is still PTE.
+ *
+ * @ingroup api_circular_queue
*/
bool
dereferenceable() const
@@ -209,11 +227,14 @@
/** InputIterator. */
- /** Equality operator.
+ /**
+ * Equality operator.
* Two iterators must point to the same, possibly null, circular
* queue and the same element on it, including PTE, to be equal.
* In case the clients the the PTE iterator and then grow on the
back
* and expect it to work, we have to check if the PTE is still PTE
+ *
+ * @ingroup api_circular_queue
*/
bool operator==(const iterator& that) const
{
@@ -221,42 +242,62 @@
_round == that._round;
}
- /** Inequality operator.
+ /**
+ * Inequality operator.
* Conversely, two iterators are different if they both point to
* different circular queues or they point to different elements.
+ *
+ * @ingroup api_circular_queue
*/
bool operator!=(const iterator& that)
{
return !(*this == that);
}
- /** Dereference operator. */
+ /**
+ * Dereference operator.
+ *
+ * @ingroup api_circular_queue
+ */
reference operator*()
{
/* this has to be dereferenceable. */
return (*_cq)[_idx];
}
+ /**
+ * @ingroup api_circular_queue
+ */
const_reference operator*() const
{
/* this has to be dereferenceable. */
return (*_cq)[_idx];
}
- /** Dereference operator.
+ /**
+ * Dereference operator.
* Rely on operator* to check for dereferenceability.
+ *
+ * @ingroup api_circular_queue
*/
pointer operator->()
{
return &((*_cq)[_idx]);
}
+ /**
+ * @ingroup api_circular_queue
+ */
const_pointer operator->() const
{
return &((*_cq)[_idx]);
}
- /** Pre-increment operator. */
+ /**
+ * Pre-increment operator.
+ *
+ * @ingroup api_circular_queue
+ */
iterator& operator++()
{
/* this has to be dereferenceable. */
@@ -266,7 +307,11 @@
return *this;
}
- /** Post-increment operator. */
+ /**
+ * Post-increment operator.
+ *
+ * @ingroup api_circular_queue
+ */
iterator
operator++(int)
{
@@ -298,7 +343,11 @@
}
public:
- /** Pre-decrement operator. */
+ /**
+ * Pre-decrement operator.
+ *
+ * @ingroup api_circular_queue
+ */
iterator& operator--()
{
/* this has to be decrementable. */
@@ -309,10 +358,18 @@
return *this;
}
- /** Post-decrement operator. */
+ /**
+ * Post-decrement operator.
+ *
+ * @ingroup api_circular_queue
+ */
iterator operator--(int ) { iterator t = *this; --*this; return t;
}
- /** RandomAccessIterator requirements.*/
+ /**
+ * RandomAccessIterator requirements.
+ *
+ * @ingroup api_circular_queue
+ */
iterator& operator+=(const difference_type& t)
{
assert(_cq);
@@ -321,6 +378,9 @@
return *this;
}
+ /**
+ * @ingroup api_circular_queue
+ */
iterator& operator-=(const difference_type& t)
{
assert(_cq);
@@ -335,34 +395,51 @@
return *this;
}
- /** Addition operator. */
+ /**
+ * Addition operator.
+ *
+ * @ingroup api_circular_queue
+ */
iterator operator+(const difference_type& t)
{
iterator ret(*this);
return ret += t;
}
+ /**
+ * @ingroup api_circular_queue
+ */
friend iterator operator+(const difference_type& t, iterator& it)
{
iterator ret = it;
return ret += t;
}
- /** Substraction operator. */
+ /**
+ * Substraction operator.
+ *
+ * @ingroup api_circular_queue
+ */
iterator operator-(const difference_type& t)
{
iterator ret(*this);
return ret -= t;
}
+ /**
+ * @ingroup api_circular_queue
+ */
friend iterator operator-(const difference_type& t, iterator& it)
{
iterator ret = it;
return ret -= t;
}
- /** Difference operator.
+ /**
+ * Difference operator.
* that + ret == this
+ *
+ * @ingroup api_circular_queue
*/
difference_type operator-(const iterator& that)
{
@@ -375,14 +452,21 @@
return ret;
}
- /** Index operator.
+ /**
+ * Index operator.
* The use of * tests for dereferenceability.
+ *
+ * @ingroup api_circular_queue
*/
template<typename Idx>
typename
std::enable_if<std::is_integral<Idx>::value,reference>::type
operator[](const Idx& index) { return *(*this + index); }
- /** Comparisons. */
+ /**
+ * Comparisons.
+ *
+ * @ingroup api_circular_queue
+ */
bool
operator<(const iterator& that) const
{
@@ -391,13 +475,22 @@
(this->_round == that._round && _idx < that._idx);
}
+ /**
+ * @ingroup api_circular_queue
+ */
bool
operator>(const iterator& that) const
{ return !(*this <= that); }
+ /**
+ * @ingroup api_circular_queue
+ */
bool operator>=(const iterator& that) const
{ return !(*this < that); }
+ /**
+ * @ingroup api_circular_queue
+ */
bool operator<=(const iterator& that) const
{ return !(that < *this); }
@@ -406,8 +499,14 @@
};
public:
+ /**
+ * @ingroup api_circular_queue
+ */
using Base::operator[];
+ /**
+ * @ingroup api_circular_queue
+ */
explicit CircularQueue(uint32_t size = 0)
: _capacity(size), _head(1), _tail(0), _empty(true), _round(0)
{
@@ -419,6 +518,8 @@
*
* Note: This does not actually remove elements from the backing
* store.
+ *
+ * @ingroup api_circular_queue
*/
void flush()
{
@@ -428,7 +529,11 @@
_empty = true;
}
- /** Test if the index is in the range of valid elements. */
+ /**
+ * Test if the index is in the range of valid elements.
+ *
+ * @ingroup api_circular_queue
+ */
bool isValidIdx(size_t idx) const
{
/* An index is invalid if:
@@ -449,8 +554,11 @@
)) || (_tail < idx && idx < _head));
}
- /** Test if the index is in the range of valid elements.
+ /**
+ * Test if the index is in the range of valid elements.
* The round counter is used to disambiguate aliasing.
+ *
+ * @ingroup api_circular_queue
*/
bool isValidIdx(size_t idx, uint32_t round) const
{
@@ -486,12 +594,34 @@
));
}
+ /**
+ * @ingroup api_circular_queue
+ */
reference front() { return (*this)[_head]; }
+
+ /**
+ * @ingroup api_circular_queue
+ */
reference back() { return (*this)[_tail]; }
+
+ /**
+ * @ingroup api_circular_queue
+ */
uint32_t head() const { return _head; }
+
+ /**
+ * @ingroup api_circular_queue
+ */
uint32_t tail() const { return _tail; }
+
+ /**
+ * @ingroup api_circular_queue
+ */
size_t capacity() const { return _capacity; }
+ /**
+ * @ingroup api_circular_queue
+ */
uint32_t size() const
{
if (_empty)
@@ -519,6 +649,8 @@
* had only one value prior to insertion.
*
* @params num_elem number of elements to remove
+ *
+ * @ingroup api_circular_queue
*/
void pop_front(size_t num_elem = 1)
{
@@ -530,7 +662,11 @@
_head = hIt._idx;
}
- /** Circularly decrease the tail pointer. */
+ /**
+ * Circularly decrease the tail pointer.
+ *
+ * @ingroup api_circular_queue
+ */
void pop_back()
{
assert (!_empty);
@@ -540,15 +676,22 @@
decrease(_tail);
}
- /** Pushes an element at the end of the queue. */
+ /**
+ * Pushes an element at the end of the queue.
+ *
+ * @ingroup api_circular_queue
+ */
void push_back(typename Base::value_type val)
{
advance_tail();
(*this)[_tail] = val;
}
- /** Increases the tail by one.
+ /**
+ * Increases the tail by one.
* Check for wrap-arounds to update the round counter.
+ *
+ * @ingroup api_circular_queue
*/
void advance_tail()
{
@@ -562,9 +705,12 @@
_empty = false;
}
- /** Increases the tail by a specified number of steps
+ /**
+ * Increases the tail by a specified number of steps
*
* @param len Number of steps
+ *
+ * @ingroup api_circular_queue
*/
void advance_tail(uint32_t len)
{
@@ -572,13 +718,20 @@
advance_tail();
}
- /** Is the queue empty? */
+ /**
+ * Is the queue empty?
+ *
+ * @ingroup api_circular_queue
+ */
bool empty() const { return _empty; }
- /** Is the queue full?
+ /**
+ * Is the queue full?
* A queue is full if the head is the 0^{th} element and the tail is
* the (size-1)^{th} element, or if the head is the n^{th} element and
* the tail the (n-1)^{th} element.
+ *
+ * @ingroup api_circular_queue
*/
bool full() const
{
@@ -586,7 +739,11 @@
(_tail + 1 == _head || (_tail + 1 == _capacity && _head == 0));
}
- /** Iterators. */
+ /**
+ * Iterators.
+ *
+ * @ingroup api_circular_queue
+ */
iterator begin()
{
if (_empty)
@@ -598,6 +755,9 @@
}
/* TODO: This should return a const_iterator. */
+ /**
+ * @ingroup api_circular_queue
+ */
iterator begin() const
{
if (_empty)
@@ -610,6 +770,9 @@
_round);
}
+ /**
+ * @ingroup api_circular_queue
+ */
iterator end()
{
auto poi = moduloAdd(_tail, 1);
@@ -619,6 +782,9 @@
return iterator(this, poi, round);
}
+ /**
+ * @ingroup api_circular_queue
+ */
iterator end() const
{
auto poi = moduloAdd(_tail, 1);
@@ -628,11 +794,14 @@
return iterator(const_cast<CircularQueue*>(this), poi, round);
}
- /** Return an iterator to an index in the vector.
+ /**
+ * Return an iterator to an index in the vector.
* This poses the problem of round determination. By convention, the
round
* is picked so that isValidIndex(idx, round) is true. If that is not
* possible, then the round value is _round, unless _tail is at the
end of
* the storage, in which case the PTE wraps up and becomes _round + 1
+ *
+ * @ingroup api_circular_queue
*/
iterator getIterator(size_t idx)
{
--
To view, visit https://gem5-review.googlesource.com/c/public/gem5/+/32962
To unsubscribe, or for help writing mail filters, visit
https://gem5-review.googlesource.com/settings
Gerrit-Project: public/gem5
Gerrit-Branch: develop
Gerrit-Change-Id: I0e6a89a3e3d14a6d269277e1ffeea1ed49d8e1e4
Gerrit-Change-Number: 32962
Gerrit-PatchSet: 1
Gerrit-Owner: Hoa Nguyen <hoangu...@ucdavis.edu>
Gerrit-MessageType: newchange
_______________________________________________
gem5-dev mailing list -- gem5-dev@gem5.org
To unsubscribe send an email to gem5-dev-le...@gem5.org
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
