X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FUtils%2FStatistics.hh;h=4148ba10b9532c17a8d768b070d63350d9c2fb3b;hb=7661548b20e6c7627f54bff87e0758396fd523ef;hp=6409ab1d5c6693aa76892fe072fb7f28e747ca82;hpb=601d1f509f5bb24df167a4dd5a20da67a0af9af8;p=senf.git diff --git a/senf/Utils/Statistics.hh b/senf/Utils/Statistics.hh index 6409ab1..4148ba1 100644 --- a/senf/Utils/Statistics.hh +++ b/senf/Utils/Statistics.hh @@ -1,6 +1,6 @@ // $Id$ // -// Copyright (C) 2008 +// Copyright (C) 2008 // Fraunhofer Institute for Open Communication Systems (FOKUS) // Competence Center NETwork research (NET), St. Augustin, GERMANY // Stefan Bund @@ -36,18 +36,18 @@ #include #include #include "Exception.hh" -#include "Logger/Logger.hh" -#include "Console/Console.hh" +#include +#include //#include "Statistics.mpp" -///////////////////////////////hh.p//////////////////////////////////////// +//-///////////////////////////////////////////////////////////////////////////////////////////////// namespace senf { /** \defgroup senf_statistics Statistics The statistics functionality has two parts: - + \li the senf::Statistics class \li statistics sources @@ -55,16 +55,16 @@ namespace senf { 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. */ class Collector; class Statistics; - + /** \brief Internal: Generic Statistics collection */ class StatisticsBase - { + { typedef std::map Children; struct Transform { @@ -78,7 +78,7 @@ namespace senf { struct OutputEntry; public: - /////////////////////////////////////////////////////////////////////////// + //-//////////////////////////////////////////////////////////////////////// // Types typedef boost::iterator_range CollectorRange; @@ -111,7 +111,7 @@ namespace senf { // Function object struct Collector { - void operator()(float min, float avg, float max) + void operator()(float min, float avg, float max, float dev) { ... } }; \endcode @@ -125,7 +125,7 @@ namespace senf { template Owner & connect(Target & target, std::string label="") const; ///< Connect externally managed target - template Owner & connect(std::auto_ptr target, + template Owner & connect(std::auto_ptr target, std::string label="") const; ///< Connect internally managed target Owner & noconnect() const; ///< Don't connect the output @@ -136,7 +136,7 @@ namespace senf { private: #endif OutputProxy(Owner * owner, OutputEntry * entry); - template + template OutputProxy(Owner * owner, OutputProxy const & other); private: @@ -145,30 +145,39 @@ 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 float max() const; ///< Last max value entered + float dev() const; ///< Last dev value entered virtual unsigned rank() const; ///< Return collectors rank value /**< \returns number of basic values collected into each new value by this collector. */ - ///\} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// ///\name Child collectors - ///\{ + //\{ Collector & operator[](unsigned rank); ///< Get child collector /**< This member will return a reference to the collector collecting \a rank values. \param[in] rank Number of values the requested - collector collects into each combined value. + 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 @@ -186,7 +195,7 @@ namespace senf { Statistics & base(); ///< Get base statistics object /**< Returns the base statistics object. If this is a child collector, this will return the outermost - statistics object, otherwise it will return + statistics object, otherwise it will return \c *this. */ std::string path() const; ///< Get the path to this collector @@ -195,8 +204,8 @@ namespace senf { is empty, otherwise it is built by joining the collector ranks. */ - ///\} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// ///\name Result generation OutputProxy output(unsigned n = 1u); @@ -212,8 +221,8 @@ namespace senf { \endcode \param[in] n size of sliding average window */ - ///\} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// // Exceptions struct InvalidRankException : public senf::Exception @@ -227,27 +236,28 @@ namespace senf { protected: StatisticsBase(); virtual ~StatisticsBase(); - void enter(float min, float avg, float max); + 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_; float max_; + float dev_; Children children_; - + struct QueueEntry { float min; float avg; float max; - QueueEntry() : min(), avg(), max() {} - QueueEntry(float min_, float avg_, float max_) - : min(min_), avg(avg_), max(max_) {} + float dev; + QueueEntry() : min(), avg(), max(), dev() {} + QueueEntry(float min_, float avg_, float max_, float dev_) + : min(min_), avg(avg_), max(max_), dev(dev_) {} }; typedef std::deque Queue; Queue queue_; @@ -264,7 +274,7 @@ namespace senf { struct Target : public TargetBase { boost::scoped_ptr target_; - Target(std::auto_ptr target, std::string const & label) + Target(std::auto_ptr target, std::string const & label) : TargetBase (label), target_ (target.release()) {} explicit Target(std::string const & label) : TargetBase (label), target_ (0) {} @@ -282,8 +292,9 @@ namespace senf { float min; float avg; float max; + float dev; - boost::signal signal; + boost::signal signal; boost::ptr_vector targets_; senf::console::ScopedDirectory<> dir; @@ -333,7 +344,7 @@ namespace senf { .collect(10u) // seconds .collect(60u) // minutes .collect(60u); // hours - + packetStats[10u].collect(100u); // 100 seconds rateAnalyzer.startStatistics(senf::ClockService::milliseconds(100u)); @@ -378,8 +389,8 @@ namespace senf { statslog.route(); \endcode - We use a StatisticsLogger to send the log messages to the senf::StatisticsStream log - stream. The stream, area an level to send the statistics log messages to may be configured + We use a StatisticsLogger to send the %log messages to the senf::StatisticsStream %log + stream. The stream, area an level to send the statistics %log messages to may be configured using template arguments to StatisticsLogger. It is also possible to skip sending the output to any target or send one output to several @@ -406,7 +417,7 @@ namespace senf { \see senf::StatisticsBase::OutputProxy for the output proxy (connect) interface \ingroup senf_statistics */ - class Statistics + class Statistics : public StatisticsBase, boost::noncopyable { public: @@ -416,22 +427,40 @@ namespace senf { Statistics(); - void operator()(float min, float avg, float max); + 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 */ - - void operator()(float value); ///< Same as enter() with \a min == \a avg == \a max + \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 operator() with \a min == \a avg == \a max /**< Provided so a Statistics instance can be directly used as a signal target. */ @@ -457,20 +486,21 @@ namespace senf { class Collector : public StatisticsBase { public: - virtual unsigned rank() const; + virtual unsigned rank() const; StatisticsBase::OutputProxy output(unsigned n = 1u); - + private: Collector(StatisticsBase * owner, unsigned rank); - void enter(float min, float avg, float max); + void enter(unsigned n, float min, float avg, float max, float dev); Statistics & v_base(); std::string v_path() const; unsigned rank_; unsigned i_; float accMin_; - float accAvg_; + float accSum_; + float accSumSq_; float accMax_; StatisticsBase * owner_; @@ -479,7 +509,7 @@ namespace senf { } -///////////////////////////////hh.e//////////////////////////////////////// +//-///////////////////////////////////////////////////////////////////////////////////////////////// #include "Statistics.cci" //#include "Statistics.ct" #include "Statistics.cti"