X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FUtils%2FStatistics.hh;h=4d64692f2526688f0cde97d1f0bf7b941fdf9a91;hb=refs%2Fheads%2Fmaster;hp=b4cf0bfc00f2f13393b30d359cb76fe20d791b21;hpb=9cb871b939efe93e35dd96808d25089399acfc46;p=senf.git diff --git a/senf/Utils/Statistics.hh b/senf/Utils/Statistics.hh index b4cf0bf..4d64692 100644 --- a/senf/Utils/Statistics.hh +++ b/senf/Utils/Statistics.hh @@ -2,23 +2,28 @@ // // Copyright (C) 2008 // Fraunhofer Institute for Open Communication Systems (FOKUS) -// Competence Center NETwork research (NET), St. Augustin, GERMANY -// Stefan Bund // -// This program is free software; you can redistribute it and/or modify -// it under the terms of the GNU General Public License as published by -// the Free Software Foundation; either version 2 of the License, or -// (at your option) any later version. +// The contents of this file are subject to the Fraunhofer FOKUS Public License +// Version 1.0 (the "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// http://senf.berlios.de/license.html // -// This program is distributed in the hope that it will be useful, -// but WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -// GNU General Public License for more details. +// The Fraunhofer FOKUS Public License Version 1.0 is based on, +// but modifies the Mozilla Public License Version 1.1. +// See the full license text for the amendments. // -// You should have received a copy of the GNU General Public License -// along with this program; if not, write to the -// Free Software Foundation, Inc., -// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +// Software distributed under the License is distributed on an "AS IS" basis, +// WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License +// for the specific language governing rights and limitations under the License. +// +// The Original Code is Fraunhofer FOKUS code. +// +// The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V. +// (registered association), Hansastraße 27 c, 80686 Munich, Germany. +// All Rights Reserved. +// +// Contributor(s): +// Stefan Bund /** \file \brief Statistics public header */ @@ -35,12 +40,13 @@ #include #include #include -#include "Exception.hh" #include -#include +#include +#include "StatisticAccumulator.hh" +#include "Exception.hh" //#include "Statistics.mpp" -///////////////////////////////hh.p//////////////////////////////////////// +//-///////////////////////////////////////////////////////////////////////////////////////////////// namespace senf { @@ -49,13 +55,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. */ @@ -67,6 +74,7 @@ namespace senf { { typedef std::map Children; + // why we can't use ::__gnu_cxx::select2nd instead?!?! struct Transform { typedef Children::value_type & first_argument_type; typedef Collector & result_type; @@ -78,7 +86,7 @@ namespace senf { struct OutputEntry; public: - /////////////////////////////////////////////////////////////////////////// + //-//////////////////////////////////////////////////////////////////////// // Types typedef boost::iterator_range CollectorRange; @@ -146,9 +154,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 +167,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 +180,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 +212,8 @@ namespace senf { is empty, otherwise it is built by joining the collector ranks. */ - ///\} - /////////////////////////////////////////////////////////////////////////// + //\} + //-//////////////////////////////////////////////////////////////////////// ///\name Result generation OutputProxy output(unsigned n = 1u); @@ -213,8 +229,13 @@ namespace senf { \endcode \param[in] n size of sliding average window */ - ///\} - /////////////////////////////////////////////////////////////////////////// + //\} + StatisticsData data() const; ///< Get the Statistics data as senf::StatisticsData + /**< Return a Statistic Data object containing values + from this instance. */ + + + //-//////////////////////////////////////////////////////////////////////// // Exceptions struct InvalidRankException : public senf::Exception @@ -228,14 +249,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,30 +440,58 @@ 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. */ + void operator()(StatisticsData const & data); + ///< Same as operator(), but imports statistics data from a StatisticsData object + /**< 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); - void consoleList(std::ostream & os); + void consoleList(std::ostream & os) const; void consoleCollect(std::vector & ranks); boost::shared_ptr consoleOutput( std::vector & ranks, unsigned window); @@ -469,7 +517,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 +534,7 @@ namespace senf { } -///////////////////////////////hh.e//////////////////////////////////////// +//-///////////////////////////////////////////////////////////////////////////////////////////////// #include "Statistics.cci" //#include "Statistics.ct" #include "Statistics.cti"