/*
- * SQUID Web Proxy Cache http://www.squid-cache.org/
- * ----------------------------------------------------------
+ * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
*
- * Squid is the result of efforts by numerous individuals from
- * the Internet community; see the CONTRIBUTORS file for full
- * details. Many organizations have provided support for Squid's
- * development; see the SPONSORS file for full details. Squid is
- * Copyrighted (C) 2001 by the Regents of the University of
- * California; see the COPYRIGHT file for full details. Squid
- * incorporates software developed and/or copyrighted by other
- * sources; see the CREDITS file for full details.
- *
- * 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.
- *
- * 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.
- *
- * 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, USA.
- *
- * AUTHOR: Francesco Chemolli
+ * Squid software is distributed under GPLv2+ license and includes
+ * contributions from numerous individuals and organizations.
+ * Please see the COPYING and CONTRIBUTORS files for details.
*/
#ifndef STATHIST_H_
#define STATHIST_H_
-#include "config.h"
+/* for StoreEntry */
+#include "Store.h"
-/*
- * "very generic" histogram;
- * see important comments on hbase_f restrictions in StatHist.c
- */
+/// function signature for in/out StatHist adaptation
+typedef double hbase_f(double);
-class StatHist {
+/// function signature for StatHist dumping functions
+typedef void StatHistBinDumper(StoreEntry *, int idx, double val, double size, int count);
+
+/** Generic histogram class
+ *
+ * see important comments on hbase_f restrictions in StatHist.cc
+ */
+class StatHist
+{
public:
+ /**
+ * \note the default constructor doesn't fully initialize.
+ * you have to call one of the *init functions to specialize the
+ * histogram
+ * \todo merge functionality from the *init functions to the constructor and
+ * drop these
+ * \todo specialize the class in a small hierarchy so that all
+ * relevant initializations are done at build-time
+ */
+ StatHist();
+ StatHist(const StatHist&); //not needed
+ ~StatHist() { clear(); };
+
+ typedef uint64_t bins_type;
+
+ StatHist &operator=(const StatHist &);
+
+ /** clear the contents of the histograms
+ *
+ * \todo remove: this function has been replaced in its purpose
+ * by the destructor
+ */
void clear();
- int *bins;
- int capacity;
- double min;
- double max;
- double scale;
- hbase_f *val_in; /* e.g., log() for log-based histogram */
- hbase_f *val_out; /* e.g., exp() for log based histogram */
+
+ /** Calculate the percentile for value pctile for the difference between
+ * this and the supplied histogram.
+ */
double deltaPctile(const StatHist &B, double pctile) const;
- double val(int bin) const; //todo: make private
+
+ /** obtain the output-transformed value from the specified bin
+ *
+ */
+ double val(unsigned int bin) const;
+
+ /** increment the counter for the histogram entry
+ * associated to the supplied value
+ */
void count(double val);
- StatHist &operator=(const StatHist &);
- StatHist() : bins(NULL), capacity(0), min(0), max(0), scale(1.0),
- val_in(NULL), val_out(NULL) {};
- StatHist(const StatHist&);
+
+ /** iterate the supplied bd function over the histogram values
+ */
void dump(StoreEntry *sentry, StatHistBinDumper * bd) const;
- void logInit(int capacity, double min, double max);
- void enumInit(int last_enum);
- void intInit(int n);
- void init(int capacity, hbase_f * val_in, hbase_f * val_out, double min, double max);
-private:
- int findBin(double v);
+
+ /** Initialize the Histogram using a logarithmic values distribution
+ */
+ void logInit(unsigned int capacity, double min, double max);
+
+ /** initialize the histogram to count occurrences in an enum-represented set
+ */
+ void enumInit(unsigned int last_enum);
+
+ /** Import values from another histogram
+ *
+ * \note: the two histograms MUST have the same capicity, min and max or
+ * an exception will be raised
+ */
+ StatHist &operator += (const StatHist &B);
+
+protected:
+ /** low-level initialize function. called by *Init high-level functions
+ * \note Important restrictions on val_in and val_out functions:
+ *
+ * - val_in: ascending, defined on [0, oo), val_in(0) == 0;
+ * - val_out: x == val_out(val_in(x)) where val_in(x) is defined
+ *
+ * In practice, the requirements are less strict,
+ * but then it gets hard to define them without math notation.
+ * val_in is applied after offseting the value but before scaling
+ * See log and linear based histograms for examples
+ */
+ void init(unsigned int capacity, hbase_f * val_in, hbase_f * val_out, double min, double max);
+
+ /// find what entry in the histogram corresponds to v, by applying
+ /// the preset input transformation function
+ unsigned int findBin(double v);
+
+ /// the histogram counters
+ bins_type *bins;
+ unsigned int capacity_;
+
+ /// minimum value to be stored, corresponding to the first bin
+ double min_;
+
+ /// value of the maximum counter in the histogram
+ double max_;
+
+ /// scaling factor when looking for a bin
+ double scale_;
+ hbase_f *val_in; /* e.g., log() for log-based histogram */
+ hbase_f *val_out; /* e.g., exp() for log based histogram */
};
-/* StatHist */
-void statHistCount(StatHist * H, double val);
double statHistDeltaMedian(const StatHist & A, const StatHist & B);
double statHistDeltaPctile(const StatHist & A, const StatHist & B, double pctile);
-void statHistLogInit(StatHist * H, int capacity, double min, double max);
-void statHistEnumInit(StatHist * H, int last_enum);
-void statHistIntInit(StatHist * H, int n);
StatHistBinDumper statHistEnumDumper;
StatHistBinDumper statHistIntDumper;
+inline StatHist&
+StatHist::operator =(const StatHist & src)
+{
+ if (this==&src) //handle self-assignment
+ return *this;
+ if (capacity_ != src.capacity_) {
+ xfree(bins); // xfree can handle NULL pointers, no need to check
+ capacity_=src.capacity_;
+ bins = static_cast<bins_type *>(xcalloc(src.capacity_, sizeof(bins_type)));
+ }
+ min_=src.min_;
+ max_=src.max_;
+ scale_=src.scale_;
+ val_in=src.val_in;
+ val_out=src.val_out;
+ if (bins != NULL)
+ memcpy(bins,src.bins,capacity_*sizeof(*bins));
+ return *this;
+}
+inline
+StatHist::StatHist() :
+ bins(NULL), capacity_(0), min_(0), max_(0),
+ scale_(1.0), val_in(NULL), val_out(NULL)
+{}
+inline void
+StatHist::clear()
+{
+ xfree(bins); // can handle case of bins being NULL
+ bins=NULL;
+ capacity_=0; // mark as destructed, may be needed for troubleshooting
+}
#endif /* STATHIST_H_ */
+