From: Tomek Mrugalski Date: Fri, 8 May 2015 16:19:39 +0000 (+0200) Subject: [3793] Missing descriptions added. X-Git-Tag: trac3513_base~5^2~1^2~4 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=eb1489d600d5af0d868bf1655d85e0962dac7f7a;p=thirdparty%2Fkea.git [3793] Missing descriptions added. --- diff --git a/src/lib/stats/context.h b/src/lib/stats/context.h index c9bf8c80eb..e9c05412b5 100644 --- a/src/lib/stats/context.h +++ b/src/lib/stats/context.h @@ -35,7 +35,7 @@ public: /// related to a given context together. Two examples of such contexts are /// all statistics related to a given subnet or all statistics related to a /// given network interface. -class StatContext { +struct StatContext { public: /// @brief attempts to get an observation @@ -63,6 +63,7 @@ class StatContext { std::map stats_; }; +/// @brief Pointer to the statistics context typedef boost::shared_ptr StatContextPtr; }; diff --git a/src/lib/stats/observation.h b/src/lib/stats/observation.h index f877fa0e64..5c3e440c30 100644 --- a/src/lib/stats/observation.h +++ b/src/lib/stats/observation.h @@ -38,9 +38,9 @@ public: /// @brief Defines duration resolution /// /// Boost offers a base boost::posix_time::time_duration class, that has specific -/// implementations: boost::posix_time::{hours,minutes,seconds,millisec,nanosec}. -/// For statistics purposes, the most appropriate choice seems to be milliseconds -/// precision, so we'll stick with that. +/// implementations: boost::posix_time::{hours,minutes,seconds,millisec,microsec, +/// nanosec}. For statistics purposes, the most appropriate choice seems to be +/// microseconds precision, so we'll stick with that. typedef boost::posix_time::microsec::time_duration StatsDuration; /// @defgroup stat_samples Specifies supported observation types. @@ -82,7 +82,7 @@ typedef std::pair StringSample; class Observation { public: - /// @brief type of available statistics + /// @brief Type of available statistics /// /// Note that those will later be exposed using control socket. Therefore /// an easy to understand names were chosen (integer instead of uint64). @@ -151,7 +151,7 @@ class Observation { /// @throw InvalidStatType if statistic is not integer void addValue(uint64_t value = 1); - /// @brief Records inremental floating point observation + /// @brief Records incremental floating point observation /// /// @param value floating point value observed /// @throw InvalidStatType if statistic is not fp diff --git a/src/lib/stats/stats_mgr.h b/src/lib/stats/stats_mgr.h index f1ab7f109f..3212aba86c 100644 --- a/src/lib/stats/stats_mgr.h +++ b/src/lib/stats/stats_mgr.h @@ -26,22 +26,79 @@ namespace isc { namespace stats { +/// @brief Statistics Manager class +/// +/// StatsMgr is a singleton class that represents a subsystem that manages +/// collection, storage and reporting of various types of statistics. +/// It is also the intended API for both core code and hooks. class StatsMgr : public boost::noncopyable { public: /// @brief Statistics Manager accessor method. static StatsMgr& instance(); - // methods used data producers - void addValue(const std::string& name, uint64_t value); - void addValue(const std::string& name, double value); - void addValue(const std::string& name, StatsDuration time); - void addValue(const std::string& name, const std::string& value); + /// @defgroup producer_methods Methods are used by data producers. + /// + /// @brief The following methods are used by data producers: + /// + /// @{ + + /// @brief Records absolute integer observation + /// + /// @param name name of the observation + /// @param value integer value observed + /// @throw InvalidStatType if statistic is not integer void setValue(const std::string& name, uint64_t value); + + /// @brief Records absolute floating point observation + /// + /// @param name name of the observation + /// @param value floating point value observed + /// @throw InvalidStatType if statistic is not fp void setValue(const std::string& name, double value); + + /// @brief Records absolute duration observation + /// + /// @param name name of the observation + /// @param value duration value observed + /// @throw InvalidStatType if statistic is not time duration void setValue(const std::string& name, StatsDuration value); + + /// @brief Records absolute string observation + /// + /// @param name name of the observation + /// @param value string value observed + /// @throw InvalidStatType if statistic is not a string void setValue(const std::string& name, const std::string& value); + /// @brief Records incremental integer observation + /// + /// @param name name of the observation + /// @param value integer value observed + /// @throw InvalidStatType if statistic is not integer + void addValue(const std::string& name, uint64_t value); + + /// @brief Records incremental floating point observation + /// + /// @param name name of the observation + /// @param value floating point value observed + /// @throw InvalidStatType if statistic is not fp + void addValue(const std::string& name, double value); + + /// @brief Records incremental duration observation + /// + /// @param name name of the observation + /// @param value duration value observed + /// @throw InvalidStatType if statistic is not time duration + void addValue(const std::string& name, StatsDuration time); + + /// @brief Records incremental string observation. + /// + /// @param name name of the observation + /// @param value string value observed + /// @throw InvalidStatType if statistic is not a string + void addValue(const std::string& name, const std::string& value); + /// @brief determines whether a given statistic is kept as a single value /// or as a number of values /// @@ -73,6 +130,14 @@ class StatsMgr : public boost::noncopyable { /// setMaxSampleCount("incoming-packets", 100); void setMaxSampleCount(const std::string& name, uint32_t max_samples); + /// @} + + /// @defgroup consumer_methods Methods are used by data consumers. + /// + /// @brief The following methods are used by data consumers: + /// + /// @{ + /// @brief Resets specified statistic. /// /// This is a convenience function and is equivalent to setValue(name, @@ -104,6 +169,8 @@ class StatsMgr : public boost::noncopyable { /// @return JSON structures representing all statistics isc::data::ConstElementPtr getAll() const; + /// @} + /// @brief Returns an observation /// /// Used in testing only. Production code should use @ref get() method. @@ -113,6 +180,16 @@ class StatsMgr : public boost::noncopyable { private: + /// @brief Sets a given statistic to specified value (internal version) + /// + /// This template method sets statistic identified by name to a value + /// specified by value. This internal method is used by public @ref setValue + /// methods. + /// + /// @tparam DataType one of uint64_t, double DurationStat or string + /// @param name name of the statistic + /// @param value specified statistic will be set to this value + /// @throw InvalidStatType is statistic exists and has a different type. template void setValueInternal(const std::string& name, DataType value) { ObservationPtr stat = getObservation(name); @@ -124,6 +201,16 @@ class StatsMgr : public boost::noncopyable { } } + /// @brief Adds specified value to a given statistic (internal version) + /// + /// This template method adds specified value to a given statistic (identified + /// by name to a value). This internal method is used by public @ref setValue + /// methods. + /// + /// @tparam DataType one of uint64_t, double DurationStat or string + /// @param name name of the statistic + /// @param value specified statistic will be set to this value + /// @throw InvalidStatType is statistic exists and has a different type. template void addValueInternal(const std::string& name, DataType value) { ObservationPtr existing = getObservation(name); diff --git a/src/lib/stats/tests/stats_mgr_unittest.cc b/src/lib/stats/tests/stats_mgr_unittest.cc index fbf702cefd..d1e58f7f5c 100644 --- a/src/lib/stats/tests/stats_mgr_unittest.cc +++ b/src/lib/stats/tests/stats_mgr_unittest.cc @@ -182,6 +182,8 @@ TEST_F(StatsMgrTest, getGetAll) { ConstElementPtr rep_all = StatsMgr::instance().getAll(); ASSERT_TRUE(rep_all); + std::cout << rep_all->str() << std::endl; + // Verifying this is a bit more involved, as we don't know whether the // order would be preserved or not. EXPECT_EQ(4, rep_all->size());