src/StatHist.h

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