2 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
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.
15 /// function signature for in/out StatHist adaptation
16 typedef double hbase_f(double);
18 /// function signature for StatHist dumping functions
19 typedef void StatHistBinDumper(StoreEntry
*, int idx
, double val
, double size
, int count
);
21 /** Generic histogram class
23 * see important comments on hbase_f restrictions in StatHist.cc
29 * \note the default constructor doesn't fully initialize.
30 * you have to call one of the *init functions to specialize the
32 * \todo merge functionality from the *init functions to the constructor and
34 * \todo specialize the class in a small hierarchy so that all
35 * relevant initializations are done at build-time
38 StatHist(const StatHist
&); //not needed
39 ~StatHist() { clear(); };
41 typedef uint64_t bins_type
;
43 StatHist
&operator=(const StatHist
&);
45 /** clear the contents of the histograms
47 * \todo remove: this function has been replaced in its purpose
52 /** Calculate the percentile for value pctile for the difference between
53 * this and the supplied histogram.
55 double deltaPctile(const StatHist
&B
, double pctile
) const;
57 /** obtain the output-transformed value from the specified bin
60 double val(unsigned int bin
) const;
62 /** increment the counter for the histogram entry
63 * associated to the supplied value
65 void count(double val
);
67 /** iterate the supplied bd function over the histogram values
69 void dump(StoreEntry
*sentry
, StatHistBinDumper
* bd
) const;
71 /** Initialize the Histogram using a logarithmic values distribution
73 void logInit(unsigned int capacity
, double min
, double max
);
75 /** initialize the histogram to count occurrences in an enum-represented set
77 void enumInit(unsigned int last_enum
);
79 /** Import values from another histogram
81 * \note: the two histograms MUST have the same capicity, min and max or
82 * an exception will be raised
84 StatHist
&operator += (const StatHist
&B
);
87 /** low-level initialize function. called by *Init high-level functions
88 * \note Important restrictions on val_in and val_out functions:
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
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
98 void init(unsigned int capacity
, hbase_f
* val_in
, hbase_f
* val_out
, double min
, double max
);
100 /// find what entry in the histogram corresponds to v, by applying
101 /// the preset input transformation function
102 unsigned int findBin(double v
);
104 /// the histogram counters
106 unsigned int capacity_
;
108 /// minimum value to be stored, corresponding to the first bin
111 /// value of the maximum counter in the histogram
114 /// scaling factor when looking for a bin
116 hbase_f
*val_in
; /* e.g., log() for log-based histogram */
117 hbase_f
*val_out
; /* e.g., exp() for log based histogram */
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
;
126 StatHist::operator =(const StatHist
& src
)
128 if (this==&src
) //handle self-assignment
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
)));
141 memcpy(bins
,src
.bins
,capacity_
*sizeof(*bins
));
146 StatHist::StatHist() :
147 bins(NULL
), capacity_(0), min_(0), max_(0),
148 scale_(1.0), val_in(NULL
), val_out(NULL
)
154 xfree(bins
); // can handle case of bins being NULL
156 capacity_
=0; // mark as destructed, may be needed for troubleshooting
159 #endif /* STATHIST_H_ */