folly::Histogram< T > Class Template Reference

#include <Histogram.h>

Classes
struct	AvgFromBucket
struct	CountFromBucket

Public Types
typedef T	ValueType
typedef detail::Bucket< T >	Bucket

Public Member Functions
	Histogram (ValueType bucketSize, ValueType min, ValueType max)
void	addValue (ValueType value)
void	addRepeatedValue (ValueType value, uint64_t nSamples)
void	removeValue (ValueType value)
void	removeRepeatedValue (ValueType value, uint64_t nSamples)
void	clear ()
void	subtract (const Histogram &hist)
void	merge (const Histogram &hist)
void	copy (const Histogram &hist)
ValueType	getBucketSize () const
ValueType	getMin () const
ValueType	getMax () const
size_t	getNumBuckets () const
const Bucket &	getBucketByIndex (size_t idx) const
ValueType	getBucketMin (size_t idx) const
ValueType	getBucketMax (size_t idx) const
uint64_t	computeTotalCount () const
size_t	getPercentileBucketIdx (double pct, double *lowPct=nullptr, double *highPct=nullptr) const
ValueType	getPercentileEstimate (double pct) const
std::string	debugString () const
void	toTSV (std::ostream &out, bool skipEmptyBuckets=true) const

Static Private Member Functions
template<typename S , typename = _t<std::enable_if<std::is_integral<S>::value>>>
static constexpr _t< std::make_unsigned< S > >	to_unsigned (S s)
template<typename S , typename = _t<std::enable_if<!std::is_integral<S>::value>>>
static constexpr S	to_unsigned (S s)

Private Attributes
detail::HistogramBuckets< ValueType, Bucket >	buckets_

Detailed Description

template<typename T>
class folly::Histogram< T >

Definition at line 243 of file Histogram.h.

Member Typedef Documentation

template<typename T>

typedef detail::Bucket<T> folly::Histogram< T >::Bucket

Definition at line 246 of file Histogram.h.

template<typename T>

typedef T folly::Histogram< T >::ValueType

Definition at line 245 of file Histogram.h.

Constructor & Destructor Documentation

template<typename T>

folly::Histogram< T >::Histogram ( ValueType  bucketSize, ValueType  min, ValueType  max  )

inline

Definition at line 248 of file Histogram.h.

      : buckets_(bucketSize, min, max, Bucket()) {}

Member Function Documentation

template<typename T>

void folly::Histogram< T >::addRepeatedValue ( ValueType  value, uint64_t  nSamples  )

inline

Definition at line 263 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, folly::detail::Bucket< T >::count, folly::detail::Bucket< T >::sum, and folly::to_unsigned().

                                                            {
    Bucket& bucket = buckets_.getByValue(value);
    // NOTE: Overflow is handled elsewhere and tests check this
    // behavior (see HistogramTest.cpp TestOverflow* tests).
    // TODO: It would be nice to handle overflow here and redesign this class.
    auto const addend = to_unsigned(value) * nSamples;
    bucket.sum = static_cast<ValueType>(to_unsigned(bucket.sum) + addend);
    bucket.count += nSamples;
  }

template<typename T>

void folly::Histogram< T >::addValue ( ValueType  value )

inline

Definition at line 252 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, folly::detail::Bucket< T >::count, folly::detail::Bucket< T >::sum, and folly::to_unsigned().

Referenced by addValue(), and TEST().

                                 {
    Bucket& bucket = buckets_.getByValue(value);
    // NOTE: Overflow is handled elsewhere and tests check this
    // behavior (see HistogramTest.cpp TestOverflow* tests).
    // TODO: It would be nice to handle overflow here and redesign this class.
    auto const addend = to_unsigned(value);
    bucket.sum = static_cast<ValueType>(to_unsigned(bucket.sum) + addend);
    bucket.count += 1;
  }

template<typename T>

void folly::Histogram< T >::clear ( )

inline

Definition at line 309 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, and i.

               {
    for (size_t i = 0; i < buckets_.getNumBuckets(); i++) {
      buckets_.getByIndex(i).clear();
    }
  }

template<typename T>

uint64_t folly::Histogram< T >::computeTotalCount ( ) const

inline

Computes the total number of values stored across all buckets.

Runs in O(numBuckets)

Definition at line 405 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_.

Referenced by TEST().

                                     {
    CountFromBucket countFn;
    return buckets_.computeTotalCount(countFn);
  }

template<typename T>

void folly::Histogram< T >::copy ( const Histogram< T > &  hist )

inline

Definition at line 344 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, folly::Histogram< T >::buckets_, folly::detail::HistogramBuckets< T, BucketT >::getBucketSize(), folly::Histogram< T >::getBucketSize(), folly::detail::HistogramBuckets< T, BucketT >::getMax(), folly::Histogram< T >::getMax(), folly::detail::HistogramBuckets< T, BucketT >::getMin(), folly::Histogram< T >::getMin(), folly::detail::HistogramBuckets< T, BucketT >::getNumBuckets(), folly::Histogram< T >::getNumBuckets(), and i.

                                   {
    // the two histogram bucket definition must match
    if (getBucketSize() != hist.getBucketSize() || getMin() != hist.getMin() ||
        getMax() != hist.getMax() || getNumBuckets() != hist.getNumBuckets()) {
      throw std::invalid_argument("Cannot copy from input histogram.");
    }

    for (size_t i = 0; i < buckets_.getNumBuckets(); i++) {
      buckets_.getByIndex(i) = hist.buckets_.getByIndex(i);
    }
  }

template<typename T >

std::string folly::Histogram< T >::debugString

(

)

const

Definition at line 249 of file Histogram-defs.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, i, string, and folly::toAppend().

                                          {
  std::string ret = folly::to<std::string>(
      "num buckets: ",
      buckets_.getNumBuckets(),
      ", bucketSize: ",
      buckets_.getBucketSize(),
      ", min: ",
      buckets_.getMin(),
      ", max: ",
      buckets_.getMax(),
      "\n");

  for (size_t i = 0; i < buckets_.getNumBuckets(); ++i) {
    folly::toAppend(
        "  ",
        buckets_.getBucketMin(i),
        ": ",
        buckets_.getByIndex(i).count,
        "\n",
        &ret);
  }

  return ret;
}

template<typename T>

const Bucket& folly::Histogram< T >::getBucketByIndex ( size_t  idx ) const

inline

Definition at line 374 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_.

Referenced by folly::TimeseriesHistogram< T, CT, C >::addValues(), and TEST().

                                                   {
    return buckets_.getByIndex(idx);
  }

template<typename T>

ValueType folly::Histogram< T >::getBucketMax ( size_t  idx ) const

inline

Definition at line 396 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_.

                                           {
    return buckets_.getBucketMax(idx);
  }

template<typename T>

ValueType folly::Histogram< T >::getBucketMin ( size_t  idx ) const

inline

Definition at line 385 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_.

                                           {
    return buckets_.getBucketMin(idx);
  }

template<typename T>

ValueType folly::Histogram< T >::getBucketSize ( ) const

inline

Definition at line 357 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_.

Referenced by folly::TimeseriesHistogram< T, CT, C >::addValues(), folly::Histogram< T >::copy(), folly::Histogram< T >::merge(), and folly::Histogram< T >::subtract().

                                  {
    return buckets_.getBucketSize();
  }

template<typename T>

ValueType folly::Histogram< T >::getMax ( ) const

inline

Definition at line 365 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_.

Referenced by folly::TimeseriesHistogram< T, CT, C >::addValues(), folly::Histogram< T >::copy(), folly::Histogram< T >::merge(), and folly::Histogram< T >::subtract().

                           {
    return buckets_.getMax();
  }

template<typename T>

ValueType folly::Histogram< T >::getMin ( ) const

inline

Definition at line 361 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_.

Referenced by folly::TimeseriesHistogram< T, CT, C >::addValues(), folly::Histogram< T >::copy(), folly::Histogram< T >::merge(), and folly::Histogram< T >::subtract().

                           {
    return buckets_.getMin();
  }

template<typename T>

size_t folly::Histogram< T >::getNumBuckets ( ) const

inline

Definition at line 369 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_.

Referenced by folly::TimeseriesHistogram< T, CT, C >::addValues(), folly::Histogram< T >::copy(), folly::Histogram< T >::merge(), folly::Histogram< T >::subtract(), and TEST().

                               {
    return buckets_.getNumBuckets();
  }

template<typename T>

size_t folly::Histogram< T >::getPercentileBucketIdx ( double  pct, double *  lowPct = nullptr, double *  highPct = nullptr  ) const

inline

Definition at line 416 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_.

Referenced by TEST().

                                       {
    // We unfortunately can't use lambdas here yet;
    // Some users of this code are still built with gcc-4.4.
    CountFromBucket countFn;
    return buckets_.getPercentileBucketIdx(pct, countFn, lowPct, highPct);
  }

template<typename T>

ValueType folly::Histogram< T >::getPercentileEstimate ( double  pct ) const

inline

Estimate the value at the specified percentile.

Parameters

pct	The desired percentile to find, as a value from 0.0 to 1.0.

Returns

Returns an estimate for N, where N is the number where exactly pct percentage of the data points in the histogram are less than N.

Definition at line 434 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, and string.

Referenced by TEST().

                                                    {
    CountFromBucket countFn;
    AvgFromBucket avgFn;
    return buckets_.getPercentileEstimate(pct, countFn, avgFn);
  }

template<typename T>

void folly::Histogram< T >::merge ( const Histogram< T > &  hist )

inline

Definition at line 330 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, folly::Histogram< T >::buckets_, folly::detail::HistogramBuckets< T, BucketT >::getBucketSize(), folly::Histogram< T >::getBucketSize(), folly::detail::HistogramBuckets< T, BucketT >::getMax(), folly::Histogram< T >::getMax(), folly::detail::HistogramBuckets< T, BucketT >::getMin(), folly::Histogram< T >::getMin(), folly::detail::HistogramBuckets< T, BucketT >::getNumBuckets(), folly::Histogram< T >::getNumBuckets(), and i.

                                    {
    // the two histogram bucket definitions must match to support
    // a merge.
    if (getBucketSize() != hist.getBucketSize() || getMin() != hist.getMin() ||
        getMax() != hist.getMax() || getNumBuckets() != hist.getNumBuckets()) {
      throw std::invalid_argument("Cannot merge from input histogram.");
    }

    for (size_t i = 0; i < buckets_.getNumBuckets(); i++) {
      buckets_.getByIndex(i) += hist.buckets_.getByIndex(i);
    }
  }

template<typename T>

void folly::Histogram< T >::removeRepeatedValue ( ValueType  value, uint64_t  nSamples  )

inline

Definition at line 296 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, folly::detail::Bucket< T >::count, and folly::detail::Bucket< T >::sum.

                                                               {
    Bucket& bucket = buckets_.getByValue(value);
    // TODO: It would be nice to handle overflow here.
    if (bucket.count >= nSamples) {
      bucket.sum -= value * nSamples;
      bucket.count -= nSamples;
    } else {
      bucket.sum = ValueType();
      bucket.count = 0;
    }
  }

template<typename T>

void folly::Histogram< T >::removeValue ( ValueType  value )

inline

Definition at line 280 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, folly::detail::Bucket< T >::count, folly::detail::Bucket< T >::sum, and folly::to_unsigned().

                                    {
    Bucket& bucket = buckets_.getByValue(value);
    // NOTE: Overflow is handled elsewhere and tests check this
    // behavior (see HistogramTest.cpp TestOverflow* tests).
    // TODO: It would be nice to handle overflow here and redesign this class.
    if (bucket.count > 0) {
      auto const subtrahend = to_unsigned(value);
      bucket.sum = static_cast<ValueType>(to_unsigned(bucket.sum) - subtrahend);
      bucket.count -= 1;
    } else {
      bucket.sum = ValueType();
      bucket.count = 0;
    }
  }

template<typename T>

void folly::Histogram< T >::subtract ( const Histogram< T > &  hist )

inline

Definition at line 316 of file Histogram.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, folly::Histogram< T >::buckets_, folly::detail::HistogramBuckets< T, BucketT >::getBucketSize(), folly::Histogram< T >::getBucketSize(), folly::detail::HistogramBuckets< T, BucketT >::getMax(), folly::Histogram< T >::getMax(), folly::detail::HistogramBuckets< T, BucketT >::getMin(), folly::Histogram< T >::getMin(), folly::detail::HistogramBuckets< T, BucketT >::getNumBuckets(), folly::Histogram< T >::getNumBuckets(), and i.

                                       {
    // the two histogram bucket definitions must match to support
    // subtract.
    if (getBucketSize() != hist.getBucketSize() || getMin() != hist.getMin() ||
        getMax() != hist.getMax() || getNumBuckets() != hist.getNumBuckets()) {
      throw std::invalid_argument("Cannot subtract input histogram.");
    }

    for (size_t i = 0; i < buckets_.getNumBuckets(); i++) {
      buckets_.getByIndex(i) -= hist.buckets_.getByIndex(i);
    }
  }

template<typename T>

template<typename S , typename = _t<std::enable_if<std::is_integral<S>::value>>>

static constexpr _t<std::make_unsigned<S> > folly::Histogram< T >::to_unsigned ( S  s )

inlinestaticprivate

Definition at line 478 of file Histogram.h.

References s.

                                                            {
    return static_cast<_t<std::make_unsigned<S>>>(s);
  }

template<typename T>

template<typename S , typename = _t<std::enable_if<!std::is_integral<S>::value>>>

static constexpr S folly::Histogram< T >::to_unsigned ( S  s )

inlinestaticprivate

Definition at line 484 of file Histogram.h.

References s.

                                      {
    return s;
  }

template<typename T >

void folly::Histogram< T >::toTSV	(	std::ostream &	out,
		bool	skipEmptyBuckets = true
	)		const

Definition at line 275 of file Histogram-defs.h.

References folly::detail::HistogramBuckets< T, BucketT >::buckets_, folly::detail::HistogramBuckets< T, BucketT >::getBucketMax(), folly::detail::HistogramBuckets< T, BucketT >::getBucketMin(), and i.

                                                                     {
  for (size_t i = 0; i < buckets_.getNumBuckets(); ++i) {
    // Do not output empty buckets in order to reduce data file size.
    if (skipEmptyBuckets && getBucketByIndex(i).count == 0) {
      continue;
    }
    const auto& bucket = getBucketByIndex(i);
    out << getBucketMin(i) << '\t' << getBucketMax(i) << '\t' << bucket.count
        << '\t' << bucket.sum << '\n';
  }
}

Member Data Documentation

template<typename T>

detail::HistogramBuckets<ValueType, Bucket> folly::Histogram< T >::buckets_

private

Definition at line 488 of file Histogram.h.

Referenced by folly::Histogram< T >::copy(), folly::Histogram< T >::merge(), and folly::Histogram< T >::subtract().

---

The documentation for this class was generated from the following files:

• proxygen/folly/folly/stats/Histogram.h
• proxygen/folly/folly/stats/Histogram-defs.h