diff -r 000000000000 -r 6474c204b198 ipc/chromium/src/base/histogram.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ipc/chromium/src/base/histogram.h Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,781 @@ +// 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 +#include +#include + +#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 Counts; + typedef std::vector 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(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); } + void ClearFlags(Flags flags) { flags_ = static_cast(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 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& custom_ranges, + Flags flags); + + // Overridden from Histogram: + virtual ClassType histogram_type() const; + + protected: + CustomHistogram(const std::string& name, + const std::vector& custom_ranges); + + // Initialize ranges_ mapping. + void InitializedCustomBucketRange(const std::vector& 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 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 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_