src/StatHist.h

   1 /*
   2  * Copyright (C) 1996-2020 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() = default;
  38     StatHist(const StatHist &);
  39     ~StatHist() {
  40         xfree(bins); // can handle case of bins being nullptr
  41         capacity_ = 0;  // mark as destructed, may be needed for troubleshooting
  42     }
  43
  44     typedef uint64_t bins_type;
  45
  46     StatHist &operator=(const StatHist &);
  47
  48     /** Calculate the percentile for value pctile for the difference between
  49      *  this and the supplied histogram.
  50      */
  51     double deltaPctile(const StatHist &B, double pctile) const;
  52
  53     /** obtain the output-transformed value from the specified bin
  54      *
  55      */
  56     double val(unsigned int bin) const;
  57
  58     /** increment the counter for the histogram entry
  59      * associated to the supplied value
  60      */
  61     void count(double val);
  62
  63     /** iterate the supplied bd function over the histogram values
  64      */
  65     void dump(StoreEntry *sentry, StatHistBinDumper * bd) const;
  66
  67     /** Initialize the Histogram using a logarithmic values distribution
  68      */
  69     void logInit(unsigned int capacity, double min, double max);
  70
  71     /** initialize the histogram to count occurrences in an enum-represented set
  72      */
  73     void enumInit(unsigned int last_enum);
  74
  75     /** Import values from another histogram
  76      *
  77      * \note: the two histograms MUST have the same capicity, min and max or
  78      *      an exception will be raised
  79      */
  80     StatHist &operator += (const StatHist &B);
  81
  82 protected:
  83     /** low-level initialize function. called by *Init high-level functions
  84      * \note Important restrictions on val_in and val_out functions:
  85      *
  86      *   - val_in:  ascending, defined on [0, oo), val_in(0) == 0;
  87      *   - val_out: x == val_out(val_in(x)) where val_in(x) is defined
  88      *
  89      *  In practice, the requirements are less strict,
  90      *  but then it gets hard to define them without math notation.
  91      *  val_in is applied after offseting the value but before scaling
  92      *  See log and linear based histograms for examples
  93      */
  94     void init(unsigned int capacity, hbase_f * val_in, hbase_f * val_out, double min, double max);
  95
  96     /// find what entry in the histogram corresponds to v, by applying
  97     /// the preset input transformation function
  98     unsigned int findBin(double v);
  99
 100     /// the histogram counters
 101     bins_type *bins = nullptr;
 102     unsigned int capacity_ = 0;
 103
 104     /// minimum value to be stored, corresponding to the first bin
 105     double min_ = 0.0;
 106
 107     /// value of the maximum counter in the histogram
 108     double max_ = 0.0;
 109
 110     /// scaling factor when looking for a bin
 111     double scale_ = 1.0;
 112     hbase_f *val_in = nullptr;        /* e.g., log() for log-based histogram */
 113     hbase_f *val_out = nullptr;       /* e.g., exp() for log based histogram */
 114 };
 115
 116 double statHistDeltaMedian(const StatHist & A, const StatHist & B);
 117 double statHistDeltaPctile(const StatHist & A, const StatHist & B, double pctile);
 118 StatHistBinDumper statHistEnumDumper;
 119 StatHistBinDumper statHistIntDumper;
 120
 121 inline StatHist&
 122 StatHist::operator =(const StatHist & src)
 123 {
 124     if (this==&src) //handle self-assignment
 125         return *this;
 126     if (capacity_ != src.capacity_) {
 127         xfree(bins); // xfree can handle NULL pointers, no need to check
 128         capacity_=src.capacity_;
 129         bins = static_cast<bins_type *>(xcalloc(src.capacity_, sizeof(bins_type)));
 130     }
 131     min_=src.min_;
 132     max_=src.max_;
 133     scale_=src.scale_;
 134     val_in=src.val_in;
 135     val_out=src.val_out;
 136     if (bins)
 137         memcpy(bins,src.bins,capacity_*sizeof(*bins));
 138     return *this;
 139 }
 140
 141 #endif /* STATHIST_H_ */
 142