The Tor Browser: ipc/chromium/src/base/histogram.h@6474c204b198 (annotated)

ipc/chromium/src/base/histogram.h@6474c204b198 (annotated)

ipc/chromium/src/base/histogram.h

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 // Histogram is an object that aggregates statistics, and can summarize them in
 // various forms, including ASCII graphical, HTML, and numerically (as a
 // vector of numbers corresponding to each of the aggregating buckets).
 // It supports calls to accumulate either time intervals (which are processed
 // as integral number of milliseconds), or arbitrary integral units.
 // The default layout of buckets is exponential.  For example, buckets might
 // contain (sequentially) the count of values in the following intervals:
 // [0,1), [1,2), [2,4), [4,8), [8,16), [16,32), [32,64), [64,infinity)
 // That bucket allocation would actually result from construction of a histogram
 // for values between 1 and 64, with 8 buckets, such as:
 // Histogram count(L"some name", 1, 64, 8);
 // Note that the underflow bucket [0,1) and the overflow bucket [64,infinity)
 // are not counted by the constructor in the user supplied "bucket_count"
 // argument.
 // The above example has an exponential ratio of 2 (doubling the bucket width
 // in each consecutive bucket.  The Histogram class automatically calculates
 // the smallest ratio that it can use to construct the number of buckets
 // selected in the constructor.  An another example, if you had 50 buckets,
 // and millisecond time values from 1 to 10000, then the ratio between
 // consecutive bucket widths will be approximately somewhere around the 50th
 // root of 10000.  This approach provides very fine grain (narrow) buckets
 // at the low end of the histogram scale, but allows the histogram to cover a
 // gigantic range with the addition of very few buckets.
 // Histograms use a pattern involving a function static variable, that is a
 // pointer to a histogram.  This static is explicitly initialized on any thread
 // that detects a uninitialized (NULL) pointer.  The potentially racy
 // initialization is not a problem as it is always set to point to the same
 // value (i.e., the FactoryGet always returns the same value).  FactoryGet
 // is also completely thread safe, which results in a completely thread safe,
 // and relatively fast, set of counters.  To avoid races at shutdown, the static
 // pointer is NOT deleted, and we leak the histograms at process termination.
 #ifndef BASE_METRICS_HISTOGRAM_H_
 #define BASE_METRICS_HISTOGRAM_H_
 #pragma once
 #include "mozilla/MemoryReporting.h"
 #include <map>
 #include <string>
 #include <vector>
 #include "base/time.h"
 #include "base/lock.h"
 class Pickle;
 namespace base {
 //------------------------------------------------------------------------------
 // Provide easy general purpose histogram in a macro, just like stats counters.
 // The first four macros use 50 buckets.
 #define HISTOGRAM_TIMES(name, sample) HISTOGRAM_CUSTOM_TIMES( \
     name, sample, base::TimeDelta::FromMilliseconds(1), \
     base::TimeDelta::FromSeconds(10), 50)
 #define HISTOGRAM_COUNTS(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
     name, sample, 1, 1000000, 50)
 #define HISTOGRAM_COUNTS_100(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
     name, sample, 1, 100, 50)
 #define HISTOGRAM_COUNTS_10000(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
     name, sample, 1, 10000, 50)
 #define HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::Histogram::FactoryGet(name, min, max, bucket_count, \
                                             base::Histogram::kNoFlags); \
     DCHECK_EQ(name, counter->histogram_name()); \
     counter->Add(sample); \
   } while (0)
 #define HISTOGRAM_PERCENTAGE(name, under_one_hundred) \
     HISTOGRAM_ENUMERATION(name, under_one_hundred, 101)
 // For folks that need real specific times, use this to select a precise range
 // of times you want plotted, and the number of buckets you want used.
 #define HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
                                                 base::Histogram::kNoFlags); \
     DCHECK_EQ(name, counter->histogram_name()); \
     counter->AddTime(sample); \
   } while (0)
 // DO NOT USE THIS.  It is being phased out, in favor of HISTOGRAM_CUSTOM_TIMES.
 #define HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
                                                 base::Histogram::kNoFlags); \
     DCHECK_EQ(name, counter->histogram_name()); \
     if ((sample) < (max)) counter->AddTime(sample); \
   } while (0)
 // Support histograming of an enumerated value.  The samples should always be
 // less than boundary_value.
 #define HISTOGRAM_ENUMERATION(name, sample, boundary_value) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::LinearHistogram::FactoryGet(name, 1, boundary_value, \
           boundary_value + 1, base::Histogram::kNoFlags); \
     DCHECK_EQ(name, counter->histogram_name()); \
     counter->Add(sample); \
   } while (0)
 #define HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::CustomHistogram::FactoryGet(name, custom_ranges, \
                                                   base::Histogram::kNoFlags); \
     DCHECK_EQ(name, counter->histogram_name()); \
     counter->Add(sample); \
   } while (0)
 //------------------------------------------------------------------------------
 // Define Debug vs non-debug flavors of macros.
 #ifndef NDEBUG
 #define DHISTOGRAM_TIMES(name, sample) HISTOGRAM_TIMES(name, sample)
 #define DHISTOGRAM_COUNTS(name, sample) HISTOGRAM_COUNTS(name, sample)
 #define DHISTOGRAM_PERCENTAGE(name, under_one_hundred) HISTOGRAM_PERCENTAGE(\
     name, under_one_hundred)
 #define DHISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \
     HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count)
 #define DHISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) \
     HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count)
 #define DHISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
     HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count)
 #define DHISTOGRAM_ENUMERATION(name, sample, boundary_value) \
     HISTOGRAM_ENUMERATION(name, sample, boundary_value)
 #define DHISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \
     HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges)
 #else  // NDEBUG
 #define DHISTOGRAM_TIMES(name, sample) do {} while (0)
 #define DHISTOGRAM_COUNTS(name, sample) do {} while (0)
 #define DHISTOGRAM_PERCENTAGE(name, under_one_hundred) do {} while (0)
 #define DHISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \
     do {} while (0)
 #define DHISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) \
     do {} while (0)
 #define DHISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
     do {} while (0)
 #define DHISTOGRAM_ENUMERATION(name, sample, boundary_value) do {} while (0)
 #define DHISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \
     do {} while (0)
 #endif  // NDEBUG
 //------------------------------------------------------------------------------
 // The following macros provide typical usage scenarios for callers that wish
 // to record histogram data, and have the data submitted/uploaded via UMA.
 // Not all systems support such UMA, but if they do, the following macros
 // should work with the service.
 #define UMA_HISTOGRAM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
     name, sample, base::TimeDelta::FromMilliseconds(1), \
     base::TimeDelta::FromSeconds(10), 50)
 #define UMA_HISTOGRAM_MEDIUM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
     name, sample, base::TimeDelta::FromMilliseconds(10), \
     base::TimeDelta::FromMinutes(3), 50)
 // Use this macro when times can routinely be much longer than 10 seconds.
 #define UMA_HISTOGRAM_LONG_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
     name, sample, base::TimeDelta::FromMilliseconds(1), \
     base::TimeDelta::FromHours(1), 50)
 #define UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
             base::Histogram::kUmaTargetedHistogramFlag); \
     DCHECK_EQ(name, counter->histogram_name()); \
     counter->AddTime(sample); \
   } while (0)
 // DO NOT USE THIS.  It is being phased out, in favor of HISTOGRAM_CUSTOM_TIMES.
 #define UMA_HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
            base::Histogram::kUmaTargetedHistogramFlag); \
     DCHECK_EQ(name, counter->histogram_name()); \
     if ((sample) < (max)) counter->AddTime(sample); \
   } while (0)
 #define UMA_HISTOGRAM_COUNTS(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
     name, sample, 1, 1000000, 50)
 #define UMA_HISTOGRAM_COUNTS_100(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
     name, sample, 1, 100, 50)
 #define UMA_HISTOGRAM_COUNTS_10000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
     name, sample, 1, 10000, 50)
 #define UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::Histogram::FactoryGet(name, min, max, bucket_count, \
           base::Histogram::kUmaTargetedHistogramFlag); \
     DCHECK_EQ(name, counter->histogram_name()); \
     counter->Add(sample); \
   } while (0)
 #define UMA_HISTOGRAM_MEMORY_KB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
     name, sample, 1000, 500000, 50)
 #define UMA_HISTOGRAM_MEMORY_MB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
     name, sample, 1, 1000, 50)
 #define UMA_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \
     UMA_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101)
 #define UMA_HISTOGRAM_BOOLEAN(name, sample) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::BooleanHistogram::FactoryGet(name, \
           base::Histogram::kUmaTargetedHistogramFlag); \
     DCHECK_EQ(name, counter->histogram_name()); \
     counter->AddBoolean(sample); \
   } while (0)
 #define UMA_HISTOGRAM_ENUMERATION(name, sample, boundary_value) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::LinearHistogram::FactoryGet(name, 1, boundary_value, \
           boundary_value + 1, base::Histogram::kUmaTargetedHistogramFlag); \
     DCHECK_EQ(name, counter->histogram_name()); \
     counter->Add(sample); \
   } while (0)
 #define UMA_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) do { \
     static base::Histogram* counter(NULL); \
     if (!counter) \
       counter = base::CustomHistogram::FactoryGet(name, custom_ranges, \
           base::Histogram::kUmaTargetedHistogramFlag); \
     DCHECK_EQ(name, counter->histogram_name()); \
     counter->Add(sample); \
   } while (0)
 //------------------------------------------------------------------------------
 class BooleanHistogram;
 class CustomHistogram;
 class Histogram;
 class LinearHistogram;
 class Histogram {
  public:
   typedef int Sample;  // Used for samples (and ranges of samples).
   typedef int Count;  // Used to count samples in a bucket.
   static const Sample kSampleType_MAX = INT_MAX;
   // Initialize maximum number of buckets in histograms as 16,384.
   static const size_t kBucketCount_MAX;
   typedef std::vector<Count> Counts;
   typedef std::vector<Sample> Ranges;
   // These enums are used to facilitate deserialization of renderer histograms
   // into the browser.
   enum ClassType {
     HISTOGRAM,
     LINEAR_HISTOGRAM,
     BOOLEAN_HISTOGRAM,
     FLAG_HISTOGRAM,
     CUSTOM_HISTOGRAM,
     NOT_VALID_IN_RENDERER
   };
   enum BucketLayout {
     EXPONENTIAL,
     LINEAR,
     CUSTOM
   };
   enum Flags {
     kNoFlags = 0,
     kUmaTargetedHistogramFlag = 0x1,  // Histogram should be UMA uploaded.
     kExtendedStatisticsFlag = 0x2, // OK to gather extended statistics on histograms.
     // Indicate that the histogram was pickled to be sent across an IPC Channel.
     // If we observe this flag on a histogram being aggregated into after IPC,
     // then we are running in a single process mode, and the aggregation should
     // not take place (as we would be aggregating back into the source
     // histogram!).
     kIPCSerializationSourceFlag = 0x10,
     kHexRangePrintingFlag = 0x8000  // Fancy bucket-naming supported.
   };
   enum Inconsistencies {
     NO_INCONSISTENCIES = 0x0,
     RANGE_CHECKSUM_ERROR = 0x1,
     BUCKET_ORDER_ERROR = 0x2,
     COUNT_HIGH_ERROR = 0x4,
     COUNT_LOW_ERROR = 0x8,
     NEVER_EXCEEDED_VALUE = 0x10
   };
   struct DescriptionPair {
     Sample sample;
     const char* description;  // Null means end of a list of pairs.
   };
   size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf);
   //----------------------------------------------------------------------------
   // Statistic values, developed over the life of the histogram.
   class SampleSet {
    public:
     explicit SampleSet();
     ~SampleSet();
     // Adjust size of counts_ for use with given histogram.
     void Resize(const Histogram& histogram);
     void CheckSize(const Histogram& histogram) const;
     // Accessor for histogram to make routine additions.
     void AccumulateWithLinearStats(Sample value, Count count, size_t index);
     // Alternate routine for exponential histograms.
     // computeExpensiveStatistics should be true if we want to compute log sums.
     void AccumulateWithExponentialStats(Sample value, Count count, size_t index,
 					bool computeExtendedStatistics);
     // Accessor methods.
     Count counts(size_t i) const { return counts_[i]; }
     Count TotalCount() const;
     int64_t sum() const { return sum_; }
     uint64_t sum_squares() const { return sum_squares_; }
     double log_sum() const { return log_sum_; }
     double log_sum_squares() const { return log_sum_squares_; }
     int64_t redundant_count() const { return redundant_count_; }
     size_t size() const { return counts_.size(); }
     // Arithmetic manipulation of corresponding elements of the set.
     void Add(const SampleSet& other);
     void Subtract(const SampleSet& other);
     bool Serialize(Pickle* pickle) const;
     bool Deserialize(void** iter, const Pickle& pickle);
     size_t SizeOfExcludingThis(mozilla::MallocSizeOf aMallocSizeOf);
    protected:
     // Actual histogram data is stored in buckets, showing the count of values
     // that fit into each bucket.
     Counts counts_;
     // Save simple stats locally.  Note that this MIGHT get done in base class
     // without shared memory at some point.
     int64_t sum_;         // sum of samples.
     uint64_t sum_squares_; // sum of squares of samples.
     // These fields may or may not be updated at the discretion of the
     // histogram.  We use the natural log and compute ln(sample+1) so that
     // zeros are handled sanely.
     double log_sum_;      // sum of logs of samples.
     double log_sum_squares_; // sum of squares of logs of samples
    private:
     void Accumulate(Sample value, Count count, size_t index);
     // To help identify memory corruption, we reduntantly save the number of
     // samples we've accumulated into all of our buckets.  We can compare this
     // count to the sum of the counts in all buckets, and detect problems.  Note
     // that due to races in histogram accumulation (if a histogram is indeed
     // updated on several threads simultaneously), the tallies might mismatch,
     // and also the snapshotting code may asynchronously get a mismatch (though
     // generally either race based mismatch cause is VERY rare).
     int64_t redundant_count_;
   };
   //----------------------------------------------------------------------------
   // minimum should start from 1. 0 is invalid as a minimum. 0 is an implicit
   // default underflow bucket.
   static Histogram* FactoryGet(const std::string& name,
                                Sample minimum,
                                Sample maximum,
                                size_t bucket_count,
                                Flags flags);
   static Histogram* FactoryTimeGet(const std::string& name,
                                    base::TimeDelta minimum,
                                    base::TimeDelta maximum,
                                    size_t bucket_count,
                                    Flags flags);
   void Add(int value);
   void Subtract(int value);
   // This method is an interface, used only by BooleanHistogram.
   virtual void AddBoolean(bool value);
   // Accept a TimeDelta to increment.
   void AddTime(TimeDelta time) {
     Add(static_cast<int>(time.InMilliseconds()));
   }
   virtual void AddSampleSet(const SampleSet& sample);
   void Clear();
   // This method is an interface, used only by LinearHistogram.
   virtual void SetRangeDescriptions(const DescriptionPair descriptions[]);
   // The following methods provide graphical histogram displays.
   void WriteHTMLGraph(std::string* output) const;
   void WriteAscii(bool graph_it, const std::string& newline,
                   std::string* output) const;
   // Support generic flagging of Histograms.
   // 0x1 Currently used to mark this histogram to be recorded by UMA..
   // 0x8000 means print ranges in hex.
   void SetFlags(Flags flags) { flags_ = static_cast<Flags> (flags_ | flags); }
   void ClearFlags(Flags flags) { flags_ = static_cast<Flags>(flags_ & ~flags); }
   int flags() const { return flags_; }
   // Convenience methods for serializing/deserializing the histograms.
   // Histograms from Renderer process are serialized and sent to the browser.
   // Browser process reconstructs the histogram from the pickled version
   // accumulates the browser-side shadow copy of histograms (that mirror
   // histograms created in the renderer).
   // Serialize the given snapshot of a Histogram into a String. Uses
   // Pickle class to flatten the object.
   static std::string SerializeHistogramInfo(const Histogram& histogram,
                                             const SampleSet& snapshot);
   // The following method accepts a list of pickled histograms and
   // builds a histogram and updates shadow copy of histogram data in the
   // browser process.
   static bool DeserializeHistogramInfo(const std::string& histogram_info);
   // Check to see if bucket ranges, counts and tallies in the snapshot are
   // consistent with the bucket ranges and checksums in our histogram.  This can
   // produce a false-alarm if a race occurred in the reading of the data during
   // a SnapShot process, but should otherwise be false at all times (unless we
   // have memory over-writes, or DRAM failures).
   virtual Inconsistencies FindCorruption(const SampleSet& snapshot) const;
   //----------------------------------------------------------------------------
   // Accessors for factory constuction, serialization and testing.
   //----------------------------------------------------------------------------
   virtual ClassType histogram_type() const;
   const std::string& histogram_name() const { return histogram_name_; }
   Sample declared_min() const { return declared_min_; }
   Sample declared_max() const { return declared_max_; }
   virtual Sample ranges(size_t i) const;
   uint32_t range_checksum() const { return range_checksum_; }
   virtual size_t bucket_count() const;
   // Snapshot the current complete set of sample data.
   // Override with atomic/locked snapshot if needed.
   virtual void SnapshotSample(SampleSet* sample) const;
   virtual bool HasConstructorArguments(Sample minimum, Sample maximum,
                                        size_t bucket_count);
   virtual bool HasConstructorTimeDeltaArguments(TimeDelta minimum,
                                                 TimeDelta maximum,
                                                 size_t bucket_count);
   // Return true iff the range_checksum_ matches current ranges_ vector.
   bool HasValidRangeChecksum() const;
  protected:
   Histogram(const std::string& name, Sample minimum,
             Sample maximum, size_t bucket_count);
   Histogram(const std::string& name, TimeDelta minimum,
             TimeDelta maximum, size_t bucket_count);
   virtual ~Histogram();
   // Initialize ranges_ mapping.
   void InitializeBucketRange();
   // Method to override to skip the display of the i'th bucket if it's empty.
   virtual bool PrintEmptyBucket(size_t index) const;
   //----------------------------------------------------------------------------
   // Methods to override to create histogram with different bucket widths.
   //----------------------------------------------------------------------------
   // Find bucket to increment for sample value.
   virtual size_t BucketIndex(Sample value) const;
   // Get normalized size, relative to the ranges_[i].
   virtual double GetBucketSize(Count current, size_t i) const;
   // Recalculate range_checksum_.
   void ResetRangeChecksum();
   // Return a string description of what goes in a given bucket.
   // Most commonly this is the numeric value, but in derived classes it may
   // be a name (or string description) given to the bucket.
   virtual const std::string GetAsciiBucketRange(size_t it) const;
   //----------------------------------------------------------------------------
   // Methods to override to create thread safe histogram.
   //----------------------------------------------------------------------------
   // Update all our internal data, including histogram
   virtual void Accumulate(Sample value, Count count, size_t index);
   //----------------------------------------------------------------------------
   // Accessors for derived classes.
   //----------------------------------------------------------------------------
   void SetBucketRange(size_t i, Sample value);
   // Validate that ranges_ was created sensibly (top and bottom range
   // values relate properly to the declared_min_ and declared_max_)..
   bool ValidateBucketRanges() const;
   virtual uint32_t CalculateRangeChecksum() const;
   // Finally, provide the state that changes with the addition of each new
   // sample.
   SampleSet sample_;
  private:
   friend class StatisticsRecorder;  // To allow it to delete duplicates.
   // Post constructor initialization.
   void Initialize();
   // Checksum function for accumulating range values into a checksum.
   static uint32_t Crc32(uint32_t sum, Sample range);
   //----------------------------------------------------------------------------
   // Helpers for emitting Ascii graphic.  Each method appends data to output.
   // Find out how large the (graphically) the largest bucket will appear to be.
   double GetPeakBucketSize(const SampleSet& snapshot) const;
   // Write a common header message describing this histogram.
   void WriteAsciiHeader(const SampleSet& snapshot,
                         Count sample_count, std::string* output) const;
   // Write information about previous, current, and next buckets.
   // Information such as cumulative percentage, etc.
   void WriteAsciiBucketContext(const int64_t past, const Count current,
                                const int64_t remaining, const size_t i,
                                std::string* output) const;
   // Write textual description of the bucket contents (relative to histogram).
   // Output is the count in the buckets, as well as the percentage.
   void WriteAsciiBucketValue(Count current, double scaled_sum,
                              std::string* output) const;
   // Produce actual graph (set of blank vs non blank char's) for a bucket.
   void WriteAsciiBucketGraph(double current_size, double max_size,
                              std::string* output) const;
   //----------------------------------------------------------------------------
   // Table for generating Crc32 values.
   static const uint32_t kCrcTable[256];
   //----------------------------------------------------------------------------
   // Invariant values set at/near construction time
   // ASCII version of original name given to the constructor.  All identically
   // named instances will be coalesced cross-project.
   const std::string histogram_name_;
   Sample declared_min_;  // Less than this goes into counts_[0]
   Sample declared_max_;  // Over this goes into counts_[bucket_count_ - 1].
   size_t bucket_count_;  // Dimension of counts_[].
   // Flag the histogram for recording by UMA via metric_services.h.
   Flags flags_;
   // For each index, show the least value that can be stored in the
   // corresponding bucket. We also append one extra element in this array,
   // containing kSampleType_MAX, to make calculations easy.
   // The dimension of ranges_ is bucket_count + 1.
   Ranges ranges_;
   // For redundancy, we store a checksum of all the sample ranges when ranges
   // are generated.  If ever there is ever a difference, then the histogram must
   // have been corrupted.
   uint32_t range_checksum_;
   DISALLOW_COPY_AND_ASSIGN(Histogram);
 };
 //------------------------------------------------------------------------------
 // LinearHistogram is a more traditional histogram, with evenly spaced
 // buckets.
 class LinearHistogram : public Histogram {
  public:
   virtual ~LinearHistogram();
   /* minimum should start from 1. 0 is as minimum is invalid. 0 is an implicit
      default underflow bucket. */
   static Histogram* FactoryGet(const std::string& name,
                                Sample minimum,
                                Sample maximum,
                                size_t bucket_count,
                                Flags flags);
   static Histogram* FactoryTimeGet(const std::string& name,
                                    TimeDelta minimum,
                                    TimeDelta maximum,
                                    size_t bucket_count,
                                    Flags flags);
   // Overridden from Histogram:
   virtual ClassType histogram_type() const;
   virtual void Accumulate(Sample value, Count count, size_t index);
   // Store a list of number/text values for use in rendering the histogram.
   // The last element in the array has a null in its "description" slot.
   virtual void SetRangeDescriptions(const DescriptionPair descriptions[]);
  protected:
   LinearHistogram(const std::string& name, Sample minimum,
                   Sample maximum, size_t bucket_count);
   LinearHistogram(const std::string& name, TimeDelta minimum,
                   TimeDelta maximum, size_t bucket_count);
   // Initialize ranges_ mapping.
   void InitializeBucketRange();
   virtual double GetBucketSize(Count current, size_t i) const;
   // If we have a description for a bucket, then return that.  Otherwise
   // let parent class provide a (numeric) description.
   virtual const std::string GetAsciiBucketRange(size_t i) const;
   // Skip printing of name for numeric range if we have a name (and if this is
   // an empty bucket).
   virtual bool PrintEmptyBucket(size_t index) const;
  private:
   // For some ranges, we store a printable description of a bucket range.
   // If there is no desciption, then GetAsciiBucketRange() uses parent class
   // to provide a description.
   typedef std::map<Sample, std::string> BucketDescriptionMap;
   BucketDescriptionMap bucket_description_;
   DISALLOW_COPY_AND_ASSIGN(LinearHistogram);
 };
 //------------------------------------------------------------------------------
 // BooleanHistogram is a histogram for booleans.
 class BooleanHistogram : public LinearHistogram {
  public:
   static Histogram* FactoryGet(const std::string& name, Flags flags);
   virtual ClassType histogram_type() const;
   virtual void AddBoolean(bool value);
   virtual void Accumulate(Sample value, Count count, size_t index);
  protected:
   explicit BooleanHistogram(const std::string& name);
   DISALLOW_COPY_AND_ASSIGN(BooleanHistogram);
 };
 //------------------------------------------------------------------------------
 // FlagHistogram is like boolean histogram, but only allows a single off/on value.
 class FlagHistogram : public BooleanHistogram
 {
 public:
   static Histogram *FactoryGet(const std::string &name, Flags flags);
   virtual ClassType histogram_type() const;
   virtual void Accumulate(Sample value, Count count, size_t index);
   virtual void AddSampleSet(const SampleSet& sample);
 private:
   explicit FlagHistogram(const std::string &name);
   bool mSwitched;
   DISALLOW_COPY_AND_ASSIGN(FlagHistogram);
 };
 //------------------------------------------------------------------------------
 // CustomHistogram is a histogram for a set of custom integers.
 class CustomHistogram : public Histogram {
  public:
   static Histogram* FactoryGet(const std::string& name,
                                const std::vector<Sample>& custom_ranges,
                                Flags flags);
   // Overridden from Histogram:
   virtual ClassType histogram_type() const;
  protected:
   CustomHistogram(const std::string& name,
                   const std::vector<Sample>& custom_ranges);
   // Initialize ranges_ mapping.
   void InitializedCustomBucketRange(const std::vector<Sample>& custom_ranges);
   virtual double GetBucketSize(Count current, size_t i) const;
   DISALLOW_COPY_AND_ASSIGN(CustomHistogram);
 };
 //------------------------------------------------------------------------------
 // StatisticsRecorder handles all histograms in the system.  It provides a
 // general place for histograms to register, and supports a global API for
 // accessing (i.e., dumping, or graphing) the data in all the histograms.
 class StatisticsRecorder {
  public:
   typedef std::vector<Histogram*> Histograms;
   StatisticsRecorder();
   ~StatisticsRecorder();
   // Find out if histograms can now be registered into our list.
   static bool IsActive();
   // Register, or add a new histogram to the collection of statistics. If an
   // identically named histogram is already registered, then the argument
   // |histogram| will deleted.  The returned value is always the registered
   // histogram (either the argument, or the pre-existing registered histogram).
   static Histogram* RegisterOrDeleteDuplicate(Histogram* histogram);
   // Methods for printing histograms.  Only histograms which have query as
   // a substring are written to output (an empty string will process all
   // registered histograms).
   static void WriteHTMLGraph(const std::string& query, std::string* output);
   static void WriteGraph(const std::string& query, std::string* output);
   // Method for extracting histograms which were marked for use by UMA.
   static void GetHistograms(Histograms* output);
   // Find a histogram by name. It matches the exact name. This method is thread
   // safe.  If a matching histogram is not found, then the |histogram| is
   // not changed.
   static bool FindHistogram(const std::string& query, Histogram** histogram);
   static bool dump_on_exit() { return dump_on_exit_; }
   static void set_dump_on_exit(bool enable) { dump_on_exit_ = enable; }
   // GetSnapshot copies some of the pointers to registered histograms into the
   // caller supplied vector (Histograms).  Only histograms with names matching
   // query are returned. The query must be a substring of histogram name for its
   // pointer to be copied.
   static void GetSnapshot(const std::string& query, Histograms* snapshot);
  private:
   // We keep all registered histograms in a map, from name to histogram.
   typedef std::map<std::string, Histogram*> HistogramMap;
   static HistogramMap* histograms_;
   // lock protects access to the above map.
   static Lock* lock_;
   // Dump all known histograms to log.
   static bool dump_on_exit_;
   DISALLOW_COPY_AND_ASSIGN(StatisticsRecorder);
 };
 }  // namespace base
 #endif  // BASE_METRICS_HISTOGRAM_H_

The Tor Browser / annotate

ipc/chromium/src/base/histogram.h@6474c204b198 (annotated)

ipc/chromium/src/base/histogram.h