X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FUtils%2FStatistics.hh;h=3093b1ca0b4a8d399edfda8bbac2b4cc53872e03;hb=e9816d699770dea77c989c97ef53bf2266ce7b6b;hp=b4cf0bfc00f2f13393b30d359cb76fe20d791b21;hpb=9cb871b939efe93e35dd96808d25089399acfc46;p=senf.git diff --git a/senf/Utils/Statistics.hh b/senf/Utils/Statistics.hh index b4cf0bf..3093b1c 100644 --- a/senf/Utils/Statistics.hh +++ b/senf/Utils/Statistics.hh @@ -38,9 +38,10 @@ #include "Exception.hh" #include #include +#include "StatisticAccumulator.hh" //#include "Statistics.mpp" -///////////////////////////////hh.p//////////////////////////////////////// +//-///////////////////////////////////////////////////////////////////////////////////////////////// namespace senf { @@ -49,13 +50,14 @@ namespace senf { The statistics functionality has two parts: \li the senf::Statistics class + \li the senf::StatisticsAccumulator class \li statistics sources Each senf::Statistics instance collects information about a single parameter. Which parameter is set up by connecting the Statistics instance with an arbitrary statistics source. - %Statistics sources are + %Statistics sources are Boost Signals which are emitted periodically to provide new data. */ @@ -78,7 +80,7 @@ namespace senf { struct OutputEntry; public: - /////////////////////////////////////////////////////////////////////////// + //-//////////////////////////////////////////////////////////////////////// // Types typedef boost::iterator_range CollectorRange; @@ -146,9 +148,9 @@ namespace senf { template friend class OutputProxy; }; - /////////////////////////////////////////////////////////////////////////// + //-//////////////////////////////////////////////////////////////////////// ///\name Accessing the current value - ///\{ + //\{ float min() const; ///< Last min value entered float avg() const; ///< Last avg value entered @@ -159,10 +161,10 @@ namespace senf { /**< \returns number of basic values collected into each new value by this collector. */ - ///\} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// ///\name Child collectors - ///\{ + //\{ Collector & operator[](unsigned rank); ///< Get child collector @@ -172,6 +174,14 @@ namespace senf { collector collects into each combined value. \throws InvalidRankException if \a rank is not a valid registered rank value. */ + Collector const & operator[](unsigned rank) const; + ///< Get child collector + /**< This member will return a const reference to the + collector collecting \a rank values. + \param[in] rank Number of values the requested + collector collects into each combined value. + \throws InvalidRankException if \a rank is not a valid + registered rank value. */ CollectorRange collectors(); ///< List all child collectors /**< \returns iterator range of child collector references */ @@ -196,8 +206,8 @@ namespace senf { is empty, otherwise it is built by joining the collector ranks. */ - ///\} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// ///\name Result generation OutputProxy output(unsigned n = 1u); @@ -213,8 +223,8 @@ namespace senf { \endcode \param[in] n size of sliding average window */ - ///\} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// // Exceptions struct InvalidRankException : public senf::Exception @@ -228,14 +238,13 @@ namespace senf { protected: StatisticsBase(); virtual ~StatisticsBase(); - void enter(float min, float avg, float max, float dev); + void enter(unsigned n, float min, float avg, float max, float dev); private: virtual Statistics & v_base() = 0; virtual std::string v_path() const = 0; void generateOutput(); - void signalChildren(); float min_; float avg_; @@ -420,26 +429,50 @@ namespace senf { Statistics(); - void operator()(float min, float avg, float max, float dev=0.0f); + void operator()(unsigned n, float min, float avg, float max, float dev); ///< Enter new data - /**< This member must be called whenever a new data value is - available. It is important to call this member \e - periodically. The frequency at which this member is - called defines the basic statistics time scale. + /**< This member must be called whenever new data is + available. If \a min and \a max values are not available, this member should be called with \a min, \a avg and \a max - set to the same value. - + set to the same value. If no error estimate is + available, call with \a dev = 0. + + In the most common case, this member is to be called + periodically and \a n will be 1 on all calls. The + interval, at which this member is called then defines + the statistics time scale. + + Calling with \a n > 1 will submit the value \a n + times. This makes it possible to aggregate multiple + time slices into a single call. This does not change + the basic time scale but can change the number of + submits per unit time. If the basic time slice is + small, this allows to submit values almost arbitrarily + non-periodic. + + \param[in] n number of time-slices \param[in] min minimal data value since last call \param[in] avg average data value since last call \param[in] max maximal data values since last call \param[in] dev standard deviation of avg value */ - + void operator()(float min, float avg, float max, float dev=0.0f); + ///< Same as operator() with \a n==1 + /**< Provided so a Statistics instance can be directly used + as a signal target. */ void operator()(float value, float dev=0.0f); - ///< Same as enter() with \a min == \a avg == \a max + ///< Same as operator() with \a min == \a avg == \a max /**< Provided so a Statistics instance can be directly used as a signal target. */ + template + void operator()(unsigned n, StatisticAccumulator & sa); + ///< Same as operator() gathers values from StatisticAccumulator + /**< Provided so a Statistics instance can be directly used + as a signal target. Caution: Clears values in + StatisticAccumulator afterwards + \param[in] n number of time-slices + \param[in] sa StatisticAccumulator*/ StatisticsBase::OutputProxy output(unsigned n = 1u); @@ -469,7 +502,7 @@ namespace senf { private: Collector(StatisticsBase * owner, unsigned rank); - void enter(float min, float avg, float max, float dev); + void enter(unsigned n, float min, float avg, float max, float dev); Statistics & v_base(); std::string v_path() const; @@ -486,7 +519,7 @@ namespace senf { } -///////////////////////////////hh.e//////////////////////////////////////// +//-///////////////////////////////////////////////////////////////////////////////////////////////// #include "Statistics.cci" //#include "Statistics.ct" #include "Statistics.cti"