src/StatHist.h

   1 /*
   2  * SQUID Web Proxy Cache          http://www.squid-cache.org/
   3  * ----------------------------------------------------------
   4  *
   5  *  Squid is the result of efforts by numerous individuals from
   6  *  the Internet community; see the CONTRIBUTORS file for full
   7  *  details.   Many organizations have provided support for Squid's
   8  *  development; see the SPONSORS file for full details.  Squid is
   9  *  Copyrighted (C) 2001 by the Regents of the University of
  10  *  California; see the COPYRIGHT file for full details.  Squid
  11  *  incorporates software developed and/or copyrighted by other
  12  *  sources; see the CREDITS file for full details.
  13  *
  14  *  This program is free software; you can redistribute it and/or modify
  15  *  it under the terms of the GNU General Public License as published by
  16  *  the Free Software Foundation; either version 2 of the License, or
  17  *  (at your option) any later version.
  18  *
  19  *  This program is distributed in the hope that it will be useful,
  20  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  *  GNU General Public License for more details.
  23  *
  24  *  You should have received a copy of the GNU General Public License
  25  *  along with this program; if not, write to the Free Software
  26  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  27  */
  28
  29 #ifndef STATHIST_H_
  30 #define STATHIST_H_
  31
  32 /* for StoreEntry */
  33 #include "Store.h"
  34
  35 /// function signature for in/out StatHist adaptation
  36 typedef double hbase_f(double);
  37
  38 /// function signature for StatHist dumping functions
  39 typedef void StatHistBinDumper(StoreEntry *, int idx, double val, double size, int count);
  40
  41 /** Generic histogram class
  42  *
  43  * see important comments on hbase_f restrictions in StatHist.cc
  44  */
  45 class StatHist
  46 {
  47 public:
  48     /**
  49      * \note the default constructor doesn't fully initialize.
  50      *       you have to call one of the *init functions to specialize the
  51      *       histogram
  52      * \todo merge functionality from the *init functions to the constructor and
  53      *       drop these
  54      * \todo specialize the class in a small hierarchy so that all
  55      *       relevant initializations are done at build-time
  56      */
  57     StatHist();
  58     StatHist(const StatHist&); //not needed
  59     ~StatHist() { clear(); };
  60
  61     typedef uint64_t bins_type;
  62
  63     StatHist &operator=(const StatHist &);
  64
  65     /** clear the contents of the histograms
  66      *
  67      * \todo remove: this function has been replaced in its purpose
  68      *       by the destructor
  69      */
  70     void clear();
  71
  72     /** Calculate the percentile for value pctile for the difference between
  73      *  this and the supplied histogram.
  74      */
  75     double deltaPctile(const StatHist &B, double pctile) const;
  76     /** obtain the output-transformed value from the specified bin
  77      *
  78      */
  79     double val(unsigned int bin) const;
  80     /** increment the counter for the histogram entry
  81      * associated to the supplied value
  82      */
  83     void count(double val);
  84     /** iterate the supplied bd function over the histogram values
  85      */
  86     void dump(StoreEntry *sentry, StatHistBinDumper * bd) const;
  87     /** Initialize the Histogram using a logarithmic values distribution
  88      */
  89     void logInit(unsigned int capacity, double min, double max);
  90     /** initialize the histogram to count occurrences in an enum-represented set
  91      */
  92     void enumInit(unsigned int last_enum);
  93 protected:
  94     /** low-level initialize function. called by *Init high-level functions
  95      * \note Important restrictions on val_in and val_out functions:
  96      *
  97      *   - val_in:  ascending, defined on [0, oo), val_in(0) == 0;
  98      *   - val_out: x == val_out(val_in(x)) where val_in(x) is defined
  99      *
 100      *  In practice, the requirements are less strict,
 101      *  but then it gets hard to define them without math notation.
 102      *  val_in is applied after offseting the value but before scaling
 103      *  See log and linear based histograms for examples
 104      */
 105     void init(unsigned int capacity, hbase_f * val_in, hbase_f * val_out, double min, double max);
 106     /// find what entry in the histogram corresponds to v, by applying
 107     /// the preset input transformation function
 108     unsigned int findBin(double v);
 109     /// the histogram counters
 110     bins_type *bins;
 111     unsigned int capacity_;
 112     /// minimum value to be stored, corresponding to the first bin
 113     double min_;
 114     /// value of the maximum counter in the histogram
 115     double max_;
 116     /// scaling factor when looking for a bin
 117     double scale_;
 118     hbase_f *val_in;        /* e.g., log() for log-based histogram */
 119     hbase_f *val_out;       /* e.g., exp() for log based histogram */
 120 };
 121
 122 double statHistDeltaMedian(const StatHist & A, const StatHist & B);
 123 double statHistDeltaPctile(const StatHist & A, const StatHist & B, double pctile);
 124 StatHistBinDumper statHistEnumDumper;
 125 StatHistBinDumper statHistIntDumper;
 126
 127 inline StatHist&
 128 StatHist::operator =(const StatHist & src)
 129 {
 130     if (this==&src) //handle self-assignment
 131         return *this;
 132     if (capacity_ != src.capacity_) {
 133         xfree(bins); // xfree can handle NULL pointers, no need to check
 134         capacity_=src.capacity_;
 135         bins = static_cast<bins_type *>(xcalloc(src.capacity_, sizeof(bins_type)));
 136     }
 137     min_=src.min_;
 138     max_=src.max_;
 139     scale_=src.scale_;
 140     val_in=src.val_in;
 141     val_out=src.val_out;
 142     if (bins != NULL)
 143         memcpy(bins,src.bins,capacity_*sizeof(*bins));
 144     return *this;
 145 }
 146
 147 inline
 148 StatHist::StatHist() :
 149         bins(NULL), capacity_(0), min_(0), max_(0),
 150         scale_(1.0), val_in(NULL), val_out(NULL)
 151 {}
 152
 153 inline void
 154 StatHist::clear()
 155 {
 156     xfree(bins); // can handle case of bins being NULL
 157     bins=NULL;
 158     capacity_=0; // mark as destructed, may be needed for troubleshooting
 159 }
 160
 161 #endif /* STATHIST_H_ */