Hoa Nguyen has uploaded this change for review. (
https://gem5-review.googlesource.com/c/public/gem5/+/33215 )
Change subject: base,stats: Tag API methods in statistics.hh
......................................................................
base,stats: Tag API methods in statistics.hh
Change-Id: I92fe5c9a9ef4f8720bb3be514c5b5a62f59c8172
Signed-off-by: Hoa Nguyen <hoangu...@ucdavis.edu>
---
M src/base/statistics.hh
1 file changed, 272 insertions(+), 8 deletions(-)
diff --git a/src/base/statistics.hh b/src/base/statistics.hh
index 96cd43f..7ac11cc 100644
--- a/src/base/statistics.hh
+++ b/src/base/statistics.hh
@@ -248,6 +248,9 @@
DataWrap &operator=(const DataWrap &) = delete;
+ /**
+ * @ingroup api_stat
+ */
DataWrap(Group *parent, const char *name, const char *desc)
{
auto info = new Info(self());
@@ -269,6 +272,8 @@
* Set the name and marks this stat to print at the end of simulation.
* @param name The new name.
* @return A reference to this stat.
+ *
+ * @ingroup api_stat
*/
Derived &
name(const std::string &name)
@@ -285,6 +290,8 @@
* on vectors, dist, etc.
* @param _sep The new separator string
* @return A reference to this stat.
+ *
+ * @ingroup api_stat
*/
Derived &
setSeparator(const std::string &_sep)
@@ -302,6 +309,8 @@
* simulation.
* @param desc The new description.
* @return A reference to this stat.
+ *
+ * @ingroup api_stat
*/
Derived &
desc(const std::string &_desc)
@@ -314,6 +323,8 @@
* Set the precision and marks this stat to print at the end of
simulation.
* @param _precision The new precision
* @return A reference to this stat.
+ *
+ * @ingroup api_stat
*/
Derived &
precision(int _precision)
@@ -326,6 +337,8 @@
* Set the flags and marks this stat to print at the end of simulation.
* @param f The new flags.
* @return A reference to this stat.
+ *
+ * @ingroup api_stat
*/
Derived &
flags(Flags _flags)
@@ -339,6 +352,8 @@
* simulation.
* @param prereq The prerequisite stat.
* @return A reference to this stat.
+ *
+ * @ingroup api_stat
*/
template <class Stat>
Derived &
@@ -369,6 +384,8 @@
* @param index The subfield index.
* @param name The new name of the subfield.
* @return A reference to this stat.
+ *
+ * @ingroup api_stat
*/
Derived &
subname(off_type index, const std::string &name)
@@ -393,6 +410,8 @@
* @param index The subfield index.
* @param desc The new description of the subfield
* @return A reference to this stat.
+ *
+ * @ingroup api_stat
*/
Derived &
subdesc(off_type index, const std::string &desc)
@@ -418,6 +437,9 @@
self.data(i)->prepare(info);
}
+ /**
+ * @ingroup api_stat
+ */
void
reset()
{
@@ -444,6 +466,8 @@
/**
* @warning This makes the assumption that if you're gonna subnames a
2d
* vector, you're subnaming across all y
+ *
+ * @ingroup api_stat
*/
Derived &
ysubnames(const char **names)
@@ -457,6 +481,9 @@
return self;
}
+ /**
+ * @ingroup api_stat
+ */
Derived &
ysubname(off_type index, const std::string &subname)
{
@@ -469,6 +496,9 @@
return self;
}
+ /**
+ * @ingroup api_stat
+ */
std::string
ysubname(off_type i) const
{
@@ -694,6 +724,8 @@
/**
* Return the current value of this stat as its base type.
* @return The current value.
+ *
+ * @ingroup api_stat
*/
Counter value() const { return data()->value(); }
@@ -710,23 +742,37 @@
/**
* Increment the stat by 1. This calls the associated storage object
inc
* function.
+ *
+ * @ingroup api_stat
*/
void operator++() { data()->inc(1); }
/**
* Decrement the stat by 1. This calls the associated storage object
dec
* function.
+ *
+ * @ingroup api_stat
*/
void operator--() { data()->dec(1); }
- /** Increment the stat by 1. */
+ /**
+ * Increment the stat by 1.
+ *
+ * @ingroup api_stat
+ */
void operator++(int) { ++*this; }
- /** Decrement the stat by 1. */
+ /**
+ * Decrement the stat by 1.
+ *
+ * @ingroup api_stat
+ */
void operator--(int) { --*this; }
/**
* Set the data value to the given value. This calls the associated
storage
* object set function.
* @param v The new value.
+ *
+ * @ingroup api_stat
*/
template <typename U>
void operator=(const U &v) { data()->set(v); }
@@ -735,6 +781,8 @@
* Increment the stat by the given value. This calls the associated
* storage object inc function.
* @param v The value to add.
+ *
+ * @ingroup api_stat
*/
template <typename U>
void operator+=(const U &v) { data()->inc(v); }
@@ -743,6 +791,8 @@
* Decrement the stat by the given value. This calls the associated
* storage object dec function.
* @param v The value to substract.
+ *
+ * @ingroup api_stat
*/
template <typename U>
void operator-=(const U &v) { data()->dec(v); }
@@ -750,17 +800,34 @@
/**
* Return the number of elements, always 1 for a scalar.
* @return 1.
+ *
+ * @ingroup api_stat
*/
size_type size() const { return 1; }
+ /**
+ * @ingroup api_stat
+ */
Counter value() { return data()->value(); }
+ /**
+ * @ingroup api_stat
+ */
Result result() { return data()->result(); }
+ /**
+ * @ingroup api_stat
+ */
Result total() { return result(); }
+ /**
+ * @ingroup api_stat
+ */
bool zero() { return result() == 0.0; }
+ /**
+ * @ingroup api_stat
+ */
void reset() { data()->reset(this->info()); }
void prepare() { data()->prepare(this->info()); }
};
@@ -838,6 +905,9 @@
~ValueBase() { if (proxy) delete proxy; }
+ /**
+ * @ingroup api_stat
+ */
template <class T>
Derived &
scalar(T &value)
@@ -847,6 +917,9 @@
return this->self();
}
+ /**
+ * @ingroup api_stat
+ */
template <class T>
Derived &
functor(T &func)
@@ -862,6 +935,8 @@
* @param obj Pointer to the object whose method should be called.
* @param method Pointer of the function / method of the object.
* @return Updated stats item.
+ *
+ * @ingroup api_stat
*/
template <class T, class V>
Derived &
@@ -871,7 +946,10 @@
this->setInit();
return this->self();
}
-
+ /**
+ * @ingroup api_stat
+ * @{
+ */
Counter value() { return proxy->value(); }
Result result() const { return proxy->result(); }
Result total() const { return proxy->total(); };
@@ -880,8 +958,9 @@
std::string str() const { return proxy->str(); }
bool zero() const { return proxy->zero(); }
bool check() const { return proxy != NULL; }
- void prepare() { }
void reset() { }
+ /** @} */ // end of api_stat
+ void prepare() { }
};
//////////////////////////////////////////////////////////////////////
@@ -1069,6 +1148,9 @@
}
public:
+ /**
+ * @ingroup api_stat
+ */
void
value(VCounter &vec) const
{
@@ -1080,6 +1162,8 @@
/**
* Copy the values to a local vector and return a reference to it.
* @return A reference to a vector of the stat values.
+ *
+ * @ingroup api_stat
*/
void
result(VResult &vec) const
@@ -1092,6 +1176,8 @@
/**
* Return a total of all entries in this vector.
* @return The total of all vector entries.
+ *
+ * @ingroup api_stat
*/
Result
total() const
@@ -1104,9 +1190,14 @@
/**
* @return the number of elements in this vector.
+ *
+ * @ingroup api_stat
*/
size_type size() const { return _size; }
+ /**
+ * @ingroup api_stat
+ */
bool
zero() const
{
@@ -1116,6 +1207,9 @@
return true;
}
+ /**
+ * @ingroup api_stat
+ */
bool
check() const
{
@@ -1142,6 +1236,8 @@
* Set this vector to have the given size.
* @param size The new size.
* @return A reference to this stat.
+ *
+ * @ingroup api_stat
*/
Derived &
init(size_type size)
@@ -1155,6 +1251,8 @@
* Return a reference (ScalarProxy) to the stat at the given index.
* @param index The vector index to access.
* @return A reference of the stat.
+ *
+ * @ingroup api_stat
*/
Proxy
operator[](off_type index)
@@ -1279,6 +1377,9 @@
delete [] reinterpret_cast<char *>(storage);
}
+ /**
+ * @ingroup api_stat
+ */
Derived &
init(size_type _x, size_type _y)
{
@@ -1305,6 +1406,9 @@
return self;
}
+ /**
+ * @ingroup api_stat
+ */
Proxy
operator[](off_type index)
{
@@ -1314,12 +1418,18 @@
}
+ /**
+ * @ingroup api_stat
+ */
size_type
size() const
{
return _size;
}
+ /**
+ * @ingroup api_stat
+ */
bool
zero() const
{
@@ -1329,6 +1439,8 @@
/**
* Return a total of all entries in this vector.
* @return The total of all vector entries.
+ *
+ * @ingroup api_stat
*/
Result
total() const
@@ -1339,6 +1451,9 @@
return total;
}
+ /**
+ * @ingroup api_stat
+ */
void
prepare()
{
@@ -1355,6 +1470,8 @@
/**
* Reset stat value to default
+ *
+ * @ingroup api_stat
*/
void
reset()
@@ -1365,6 +1482,9 @@
data(i)->reset(info);
}
+ /**
+ * @ingroup api_stat
+ */
bool
check() const
{
@@ -1889,6 +2009,8 @@
* class.
* @param v The value to add.
* @param n The number of times to add it, defaults to 1.
+ *
+ * @ingroup api_stat
*/
template <typename U>
void sample(const U &v, int n = 1) { data()->sample(v, n); }
@@ -1896,14 +2018,21 @@
/**
* Return the number of entries in this stat.
* @return The number of entries.
+ *
+ * @ingroup api_stat
*/
size_type size() const { return data()->size(); }
/**
* Return true if no samples have been added.
* @return True if there haven't been any samples.
+ *
+ * @ingroup api_stat
*/
bool zero() const { return data()->zero(); }
+ /**
+ * @ingroup api_stat
+ */
void
prepare()
{
@@ -1913,6 +2042,8 @@
/**
* Reset stat value to default
+ *
+ * @ingroup api_stat
*/
void
reset()
@@ -1921,7 +2052,9 @@
}
/**
- * Add the argument distribution to the this distribution.
+ * Add the argument distribution to the this distribution.
+ *
+ * @ingroup api_stat
*/
void add(DistBase &d) { data()->add(d.data()); }
@@ -1991,18 +2124,27 @@
delete [] reinterpret_cast<char *>(storage);
}
+ /**
+ * @ingroup api_stat
+ */
Proxy operator[](off_type index)
{
assert(index < size());
return Proxy(this->self(), index);
}
+ /**
+ * @ingroup api_stat
+ */
size_type
size() const
{
return _size;
}
+ /**
+ * @ingroup api_stat
+ */
bool
zero() const
{
@@ -2012,6 +2154,9 @@
return true;
}
+ /**
+ * @ingroup api_stat
+ */
void
prepare()
{
@@ -2022,6 +2167,9 @@
data(i)->prepare(info, info->data[i]);
}
+ /**
+ * @ingroup api_stat
+ */
bool
check() const
{
@@ -2503,6 +2651,9 @@
class Scalar : public ScalarBase<Scalar, StatStor>
{
public:
+ /**
+ * @ingroup api_stat
+ */
using ScalarBase<Scalar, StatStor>::operator=;
Scalar(Group *parent = nullptr, const char *name = nullptr,
@@ -2599,6 +2750,8 @@
* @param max The maximum value of the distribution.
* @param bkt The number of values in each bucket.
* @return A reference to this distribution.
+ *
+ * @ingroup api_stat
*/
Distribution &
init(Counter min, Counter max, Counter bkt)
@@ -2634,6 +2787,8 @@
* Set the parameters of this histogram. @sa HistStor::Params
* @param size The number of buckets in the histogram
* @return A reference to this histogram.
+ *
+ * @ingroup api_stat
*/
Histogram &
init(size_type size)
@@ -2706,6 +2861,8 @@
* @param max The maximum value of the distribution.
* @param bkt The number of values in each bucket.
* @return A reference to this distribution.
+ *
+ * @ingroup api_stat
*/
VectorDistribution &
init(size_type size, Counter min, Counter max, Counter bkt)
@@ -2740,6 +2897,8 @@
* Initialize storage for this distribution.
* @param size The size of the vector.
* @return A reference to this distribution.
+ *
+ * @ingroup api_stat
*/
VectorStandardDeviation &
init(size_type size)
@@ -2770,6 +2929,8 @@
* Initialize storage for this distribution.
* @param size The size of the vector.
* @return A reference to this distribution.
+ *
+ * @ingroup api_stat
*/
VectorAverageDeviation &
init(size_type size)
@@ -2867,6 +3028,8 @@
* class.
* @param v The value to add.
* @param n The number of times to add it, defaults to 1.
+ *
+ * @ingroup api_stat
*/
template <typename U>
void sample(const U &v, int n = 1) { data()->sample(v, n); }
@@ -2874,11 +3037,15 @@
/**
* Return the number of entries in this stat.
* @return The number of entries.
+ *
+ * @ingroup api_stat
*/
size_type size() const { return data()->size(); }
/**
* Return true if no samples have been added.
* @return True if there haven't been any samples.
+ *
+ * @ingroup api_stat
*/
bool zero() const { return data()->zero(); }
@@ -2891,6 +3058,8 @@
/**
* Reset stat value to default
+ *
+ * @ingroup api_stat
*/
void
reset()
@@ -2987,6 +3156,8 @@
* Set the parameters of this histogram. @sa HistStor::Params
* @param size The number of buckets in the histogram
* @return A reference to this histogram.
+ *
+ * @ingroup api_stat
*/
SparseHistogram &
init(size_type size)
@@ -3025,9 +3196,14 @@
* Set an unitialized Formula to the given root.
* @param r The root of the expression tree.
* @return a reference to this formula.
+ *
+ * @ingroup api_stat
*/
const Formula &operator=(const Temp &r);
+ /**
+ * @ingroup api_stat
+ */
template<typename T>
const Formula &operator=(const T &v)
{
@@ -3039,6 +3215,8 @@
* Add the given tree to the existing one.
* @param r The root of the expression tree.
* @return a reference to this formula.
+ *
+ * @ingroup api_stat
*/
const Formula &operator+=(Temp r);
@@ -3046,6 +3224,8 @@
* Divide the existing tree by the given one.
* @param r The root of the expression tree.
* @return a reference to this formula.
+ *
+ * @ingroup api_stat
*/
const Formula &operator/=(Temp r);
@@ -3055,6 +3235,8 @@
* like x/y with x being a vector of size 3, then the result returned
will
* be x[0]/y, x[1]/y, x[2]/y, respectively.
* @return The result vector.
+ *
+ * @ingroup api_stat
*/
void result(VResult &vec) const;
@@ -3067,11 +3249,15 @@
* there is no Vector component, total() returns the same value as
* the first entry in the VResult val() returns.
* @return The total of the result vector.
+ *
+ * @ingroup api_stat
*/
Result total() const;
/**
* Return the number of elements in the tree.
+ *
+ * @ingroup api_stat
*/
size_type size() const;
@@ -3083,7 +3269,7 @@
void reset();
/**
- *
+ * @ingroup api_stat
*/
bool zero() const;
@@ -3141,6 +3327,8 @@
/**
* Create a new ScalarStatNode.
* @param s The ScalarStat to place in a node.
+ *
+ * @ingroup api_stat
*/
Temp(const Scalar &s)
: node(new ScalarStatNode(s.info()))
@@ -3149,6 +3337,8 @@
/**
* Create a new ScalarStatNode.
* @param s The ScalarStat to place in a node.
+ *
+ * @ingroup api_stat
*/
Temp(const Value &s)
: node(new ScalarStatNode(s.info()))
@@ -3157,6 +3347,8 @@
/**
* Create a new ScalarStatNode.
* @param s The ScalarStat to place in a node.
+ *
+ * @ingroup api_stat
*/
Temp(const Average &s)
: node(new ScalarStatNode(s.info()))
@@ -3165,17 +3357,22 @@
/**
* Create a new VectorStatNode.
* @param s The VectorStat to place in a node.
+ *
+ * @ingroup api_stat
*/
Temp(const Vector &s)
: node(new VectorStatNode(s.info()))
{ }
+ /**
+ * @ingroup api_stat
+ */
Temp(const AverageVector &s)
: node(new VectorStatNode(s.info()))
{ }
/**
- *
+ * @ingroup api_stat
*/
Temp(const Formula &f)
: node(new FormulaNode(f))
@@ -3184,6 +3381,8 @@
/**
* Create a new ScalarProxyNode.
* @param p The ScalarProxy to place in a node.
+ *
+ * @ingroup api_stat
*/
template <class Stat>
Temp(const ScalarProxy<Stat> &p)
@@ -3193,6 +3392,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(signed char value)
: node(new ConstNode<signed char>(value))
@@ -3201,6 +3402,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(unsigned char value)
: node(new ConstNode<unsigned char>(value))
@@ -3209,6 +3412,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(signed short value)
: node(new ConstNode<signed short>(value))
@@ -3217,6 +3422,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(unsigned short value)
: node(new ConstNode<unsigned short>(value))
@@ -3225,6 +3432,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(signed int value)
: node(new ConstNode<signed int>(value))
@@ -3233,6 +3442,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(unsigned int value)
: node(new ConstNode<unsigned int>(value))
@@ -3241,6 +3452,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(signed long value)
: node(new ConstNode<signed long>(value))
@@ -3249,6 +3462,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(unsigned long value)
: node(new ConstNode<unsigned long>(value))
@@ -3257,6 +3472,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(signed long long value)
: node(new ConstNode<signed long long>(value))
@@ -3265,6 +3482,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(unsigned long long value)
: node(new ConstNode<unsigned long long>(value))
@@ -3273,6 +3492,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(float value)
: node(new ConstNode<float>(value))
@@ -3281,6 +3502,8 @@
/**
* Create a ConstNode
* @param value The value of the const node.
+ *
+ * @ingroup api_stat
*/
Temp(double value)
: node(new ConstNode<double>(value))
@@ -3292,36 +3515,54 @@
* @}
*/
+/**
+ * @ingroup api_stat
+ */
inline Temp
operator+(Temp l, Temp r)
{
return Temp(std::make_shared<BinaryNode<std::plus<Result> > >(l, r));
}
+/**
+ * @ingroup api_stat
+ */
inline Temp
operator-(Temp l, Temp r)
{
return Temp(std::make_shared<BinaryNode<std::minus<Result> > >(l, r));
}
+/**
+ * @ingroup api_stat
+ */
inline Temp
operator*(Temp l, Temp r)
{
return Temp(std::make_shared<BinaryNode<std::multiplies<Result> > >(l,
r));
}
+/**
+ * @ingroup api_stat
+ */
inline Temp
operator/(Temp l, Temp r)
{
return Temp(std::make_shared<BinaryNode<std::divides<Result> > >(l,
r));
}
+/**
+ * @ingroup api_stat
+ */
inline Temp
operator-(Temp l)
{
return Temp(std::make_shared<UnaryNode<std::negate<Result> > >(l));
}
+/**
+ * @ingroup api_stat
+ */
template <typename T>
inline Temp
constant(T val)
@@ -3329,6 +3570,9 @@
return Temp(std::make_shared<ConstNode<T> >(val));
}
+/**
+ * @ingroup api_stat
+ */
template <typename T>
inline Temp
constantVector(T val)
@@ -3336,14 +3580,24 @@
return Temp(std::make_shared<ConstVectorNode<T> >(val));
}
+/**
+ * @ingroup api_stat
+ */
inline Temp
sum(Temp val)
{
return Temp(std::make_shared<SumNode<std::plus<Result> > >(val));
}
-/** Dump all statistics data to the registered outputs */
+/**
+ * Dump all statistics data to the registered outputs
+ *
+ * @ingroup api_stat
+ */
void dump();
+/**
+ * @ingroup api_stat
+ */
void reset();
void enable();
bool enabled();
@@ -3353,6 +3607,8 @@
* Register reset and dump handlers. These are the functions which
* will actually perform the whole statistics reset/dump actions
* including processing the reset/dump callbacks
+ *
+ * @ingroup api_stat
*/
typedef void (*Handler)();
@@ -3361,22 +3617,30 @@
/**
* Register a callback that should be called whenever statistics are
* reset
+ *
+ * @ingroup api_stat
*/
void registerResetCallback(const std::function<void()> &callback);
/**
* Register a callback that should be called whenever statistics are
* about to be dumped
+ *
+ * @ingroup api_stat
*/
void registerDumpCallback(const std::function<void()> &callback);
/**
* Process all the callbacks in the reset callbacks queue
+ *
+ * @ingroup api_stat
*/
void processResetQueue();
/**
* Process all the callbacks in the dump callbacks queue
+ *
+ * @ingroup api_stat
*/
void processDumpQueue();
--
To view, visit https://gem5-review.googlesource.com/c/public/gem5/+/33215
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: I92fe5c9a9ef4f8720bb3be514c5b5a62f59c8172
Gerrit-Change-Number: 33215
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
