From 2e714b5ebd40a1f4cc31c27f1ad6e49ca6d895f5 Mon Sep 17 00:00:00 2001
From: Sergey Polovko <sergey@polovko.me>
Date: Thu, 10 Feb 2022 16:47:03 +0300
Subject: Restoring authorship annotation for Sergey Polovko
<sergey@polovko.me>. Commit 2 of 2.
---
library/cpp/histogram/hdr/histogram.h | 606 +++++++++++++++++-----------------
1 file changed, 303 insertions(+), 303 deletions(-)
(limited to 'library/cpp/histogram/hdr/histogram.h')
diff --git a/library/cpp/histogram/hdr/histogram.h b/library/cpp/histogram/hdr/histogram.h
index b1b27b4c4f..5f1cebbd9f 100644
--- a/library/cpp/histogram/hdr/histogram.h
+++ b/library/cpp/histogram/hdr/histogram.h
@@ -1,303 +1,303 @@
-#pragma once
-
-#include <util/generic/ptr.h>
-#include <util/generic/noncopyable.h>
-#include <util/memory/alloc.h>
-
-struct hdr_histogram;
-
-namespace NHdr {
- /**
- * A High Dynamic Range (HDR) Histogram
- *
- * THdrHistogram supports the recording and analyzing sampled data value counts
- * across a configurable integer value range with configurable value precision
- * within the range. Value precision is expressed as the number of significant
- * digits in the value recording, and provides control over value quantization
- * behavior across the value range and the subsequent value resolution at any
- * given level.
- */
- class THistogram: public TMoveOnly {
- public:
- /**
- * Construct a histogram given the Highest value to be tracked and a number
- * of significant decimal digits. The histogram will be constructed to
- * implicitly track (distinguish from 0) values as low as 1. Default
- * allocator will be used to allocate underlying memory.
- *
- * @param highestTrackableValue The highest value to be tracked by the
- * histogram. Must be a positive integer that is literal >= 2.
- *
- * @param numberOfSignificantValueDigits Specifies the precision to use.
- * This is the number of significant decimal digits to which the
- * histogram will maintain value resolution and separation. Must be
- * a non-negative integer between 0 and 5.
- */
- THistogram(i64 highestTrackableValue, i32 numberOfSignificantValueDigits)
- : THistogram(1, highestTrackableValue, numberOfSignificantValueDigits)
- {
- }
-
- /**
- * Construct a histogram given the Lowest and Highest values to be tracked
- * and a number of significant decimal digits. Providing a
- * lowestDiscernibleValue is useful in situations where the units used for
- * the histogram's values are much smaller that the minimal accuracy
- * required. E.g. when tracking time values stated in nanosecond units,
- * where the minimal accuracy required is a microsecond, the proper value
- * for lowestDiscernibleValue would be 1000.
- *
- * @param lowestDiscernibleValue The lowest value that can be discerned
- * (distinguished from 0) by the histogram. Must be a positive
- * integer that is >= 1. May be internally rounded down to nearest
- * power of 2.
- *
- * @param highestTrackableValue The highest value to be tracked by the
- * histogram. Must be a positive integer that is
- * >= (2 * lowestDiscernibleValue).
- *
- * @param numberOfSignificantValueDigits Specifies the precision to use.
- * This is the number of significant decimal digits to which the
- * histogram will maintain value resolution and separation. Must be
- * a non-negative integer between 0 and 5.
- *
- * @param allocator Specifies allocator which will be used to allocate
- * memory for histogram.
- */
- THistogram(i64 lowestDiscernibleValue, i64 highestTrackableValue,
- i32 numberOfSignificantValueDigits,
- IAllocator* allocator = TDefaultAllocator::Instance());
-
- ~THistogram();
-
- // Histogram structure querying support -----------------------------------
-
- /**
- * @return The configured lowestDiscernibleValue
- */
- i64 GetLowestDiscernibleValue() const;
-
- /**
- * @return The configured highestTrackableValue
- */
- i64 GetHighestTrackableValue() const;
-
- /**
- * @return The configured numberOfSignificantValueDigits
- */
- i32 GetNumberOfSignificantValueDigits() const;
-
- /**
- * @return The size of allocated memory for histogram
- */
- size_t GetMemorySize() const;
-
- /**
- * @return The number of created counters
- */
- i32 GetCountsLen() const;
-
- /**
- * @return The total count of all recorded values in the histogram
- */
- i64 GetTotalCount() const;
-
- // Value recording support ------------------------------------------------
-
- /**
- * Records a value in the histogram, will round this value of to a
- * precision at or better than the NumberOfSignificantValueDigits specified
- * at construction time.
- *
- * @param value Value to add to the histogram
- * @return false if the value is larger than the HighestTrackableValue
- * and can't be recorded, true otherwise.
- */
- bool RecordValue(i64 value);
-
- /**
- * Records count values in the histogram, will round this value of to a
- * precision at or better than the NumberOfSignificantValueDigits specified
- * at construction time.
- *
- * @param value Value to add to the histogram
- * @param count Number of values to add to the histogram
- * @return false if the value is larger than the HighestTrackableValue
- * and can't be recorded, true otherwise.
- */
- bool RecordValues(i64 value, i64 count);
-
- /**
- * Records a value in the histogram and backfill based on an expected
- * interval. Value will be rounded this to a precision at or better
- * than the NumberOfSignificantValueDigits specified at contruction time.
- * This is specifically used for recording latency. If the value is larger
- * than the expectedInterval then the latency recording system has
- * experienced co-ordinated omission. This method fills in the values that
- * would have occured had the client providing the load not been blocked.
- *
- * @param value Value to add to the histogram
- * @param expectedInterval The delay between recording values
- * @return false if the value is larger than the HighestTrackableValue
- * and can't be recorded, true otherwise.
- */
- bool RecordValueWithExpectedInterval(i64 value, i64 expectedInterval);
-
- /**
- * Record a value in the histogram count times. Applies the same correcting
- * logic as {@link THistogram::RecordValueWithExpectedInterval}.
- *
- * @param value Value to add to the histogram
- * @param count Number of values to add to the histogram
- * @param expectedInterval The delay between recording values.
- * @return false if the value is larger than the HighestTrackableValue
- * and can't be recorded, true otherwise.
- */
- bool RecordValuesWithExpectedInterval(
- i64 value, i64 count, i64 expectedInterval);
-
- /**
- * Adds all of the values from rhs to this histogram. Will return the
- * number of values that are dropped when copying. Values will be dropped
- * if they around outside of [LowestDiscernibleValue, GetHighestTrackableValue].
- *
- * @param rhs Histogram to copy values from.
- * @return The number of values dropped when copying.
- */
- i64 Add(const THistogram& rhs);
-
- /**
- * Adds all of the values from rhs to this histogram. Will return the
- * number of values that are dropped when copying. Values will be dropped
- * if they around outside of [LowestDiscernibleValue, GetHighestTrackableValue].
- * Applies the same correcting logic as
- * {@link THistogram::RecordValueWithExpectedInterval}.
- *
- * @param rhs Histogram to copy values from.
- * @return The number of values dropped when copying.
- */
- i64 AddWithExpectedInterval(const THistogram& rhs, i64 expectedInterval);
-
- // Histogram Data access support ------------------------------------------
-
- /**
- * Get the lowest recorded value level in the histogram. If the histogram
- * has no recorded values, the value returned is undefined.
- *
- * @return the Min value recorded in the histogram
- */
- i64 GetMin() const;
-
- /**
- * Get the highest recorded value level in the histogram. If the histogram
- * has no recorded values, the value returned is undefined.
- *
- * @return the Max value recorded in the histogram
- */
- i64 GetMax() const;
-
- /**
- * Get the computed mean value of all recorded values in the histogram
- *
- * @return the mean value (in value units) of the histogram data
- */
- double GetMean() const;
-
- /**
- * Get the computed standard deviation of all recorded values in the histogram
- *
- * @return the standard deviation (in value units) of the histogram data
- */
- double GetStdDeviation() const;
-
- /**
- * Get the value at a given percentile.
- * Note that two values are "equivalent" in this statement if
- * {@link THistogram::ValuesAreEquivalent} would return true.
- *
- * @param percentile The percentile for which to return the associated
- * value
- * @return The value that the given percentage of the overall recorded
- * value entries in the histogram are either smaller than or
- * equivalent to. When the percentile is 0.0, returns the value
- * that all value entries in the histogram are either larger than
- * or equivalent to.
- */
- i64 GetValueAtPercentile(double percentile) const;
-
- /**
- * Get the count of recorded values at a specific value (to within the
- * histogram resolution at the value level).
- *
- * @param value The value for which to provide the recorded count
- * @return The total count of values recorded in the histogram within the
- * value range that is >= GetLowestEquivalentValue(value) and
- * <= GetHighestEquivalentValue(value)
- */
- i64 GetCountAtValue(i64 value) const;
-
- /**
- * Determine if two values are equivalent with the histogram's resolution.
- * Where "equivalent" means that value samples recorded for any two
- * equivalent values are counted in a common total count.
- *
- * @param v1 first value to compare
- * @param v2 second value to compare
- * @return True if values are equivalent with the histogram's resolution.
- */
- bool ValuesAreEqual(i64 v1, i64 v2) const;
-
- /**
- * Get the lowest value that is equivalent to the given value within the
- * histogram's resolution. Where "equivalent" means that value samples
- * recorded for any two equivalent values are counted in a common total
- * count.
- *
- * @param value The given value
- * @return The lowest value that is equivalent to the given value within
- * the histogram's resolution.
- */
- i64 GetLowestEquivalentValue(i64 value) const;
-
- /**
- * Get the highest value that is equivalent to the given value within the
- * histogram's resolution. Where "equivalent" means that value samples
- * recorded for any two equivalent values are counted in a common total
- * count.
- *
- * @param value The given value
- * @return The highest value that is equivalent to the given value within
- * the histogram's resolution.
- */
- i64 GetHighestEquivalentValue(i64 value) const;
-
- /**
- * Get a value that lies in the middle (rounded up) of the range of values
- * equivalent the given value. Where "equivalent" means that value samples
- * recorded for any two equivalent values are counted in a common total
- * count.
- *
- * @param value The given value
- * @return The value lies in the middle (rounded up) of the range of values
- * equivalent the given value.
- */
- i64 GetMedianEquivalentValue(i64 value) const;
-
- // misc functions ---------------------------------------------------------
-
- /**
- * Reset a histogram to zero - empty out a histogram and re-initialise it.
- * If you want to re-use an existing histogram, but reset everything back
- * to zero, this is the routine to use.
- */
- void Reset();
-
- const hdr_histogram* GetHdrHistogramImpl() const {
- return Data_.Get();
- }
-
- private:
- THolder<hdr_histogram> Data_;
- IAllocator* Allocator_;
- };
-}
+#pragma once
+
+#include <util/generic/ptr.h>
+#include <util/generic/noncopyable.h>
+#include <util/memory/alloc.h>
+
+struct hdr_histogram;
+
+namespace NHdr {
+ /**
+ * A High Dynamic Range (HDR) Histogram
+ *
+ * THdrHistogram supports the recording and analyzing sampled data value counts
+ * across a configurable integer value range with configurable value precision
+ * within the range. Value precision is expressed as the number of significant
+ * digits in the value recording, and provides control over value quantization
+ * behavior across the value range and the subsequent value resolution at any
+ * given level.
+ */
+ class THistogram: public TMoveOnly {
+ public:
+ /**
+ * Construct a histogram given the Highest value to be tracked and a number
+ * of significant decimal digits. The histogram will be constructed to
+ * implicitly track (distinguish from 0) values as low as 1. Default
+ * allocator will be used to allocate underlying memory.
+ *
+ * @param highestTrackableValue The highest value to be tracked by the
+ * histogram. Must be a positive integer that is literal >= 2.
+ *
+ * @param numberOfSignificantValueDigits Specifies the precision to use.
+ * This is the number of significant decimal digits to which the
+ * histogram will maintain value resolution and separation. Must be
+ * a non-negative integer between 0 and 5.
+ */
+ THistogram(i64 highestTrackableValue, i32 numberOfSignificantValueDigits)
+ : THistogram(1, highestTrackableValue, numberOfSignificantValueDigits)
+ {
+ }
+
+ /**
+ * Construct a histogram given the Lowest and Highest values to be tracked
+ * and a number of significant decimal digits. Providing a
+ * lowestDiscernibleValue is useful in situations where the units used for
+ * the histogram's values are much smaller that the minimal accuracy
+ * required. E.g. when tracking time values stated in nanosecond units,
+ * where the minimal accuracy required is a microsecond, the proper value
+ * for lowestDiscernibleValue would be 1000.
+ *
+ * @param lowestDiscernibleValue The lowest value that can be discerned
+ * (distinguished from 0) by the histogram. Must be a positive
+ * integer that is >= 1. May be internally rounded down to nearest
+ * power of 2.
+ *
+ * @param highestTrackableValue The highest value to be tracked by the
+ * histogram. Must be a positive integer that is
+ * >= (2 * lowestDiscernibleValue).
+ *
+ * @param numberOfSignificantValueDigits Specifies the precision to use.
+ * This is the number of significant decimal digits to which the
+ * histogram will maintain value resolution and separation. Must be
+ * a non-negative integer between 0 and 5.
+ *
+ * @param allocator Specifies allocator which will be used to allocate
+ * memory for histogram.
+ */
+ THistogram(i64 lowestDiscernibleValue, i64 highestTrackableValue,
+ i32 numberOfSignificantValueDigits,
+ IAllocator* allocator = TDefaultAllocator::Instance());
+
+ ~THistogram();
+
+ // Histogram structure querying support -----------------------------------
+
+ /**
+ * @return The configured lowestDiscernibleValue
+ */
+ i64 GetLowestDiscernibleValue() const;
+
+ /**
+ * @return The configured highestTrackableValue
+ */
+ i64 GetHighestTrackableValue() const;
+
+ /**
+ * @return The configured numberOfSignificantValueDigits
+ */
+ i32 GetNumberOfSignificantValueDigits() const;
+
+ /**
+ * @return The size of allocated memory for histogram
+ */
+ size_t GetMemorySize() const;
+
+ /**
+ * @return The number of created counters
+ */
+ i32 GetCountsLen() const;
+
+ /**
+ * @return The total count of all recorded values in the histogram
+ */
+ i64 GetTotalCount() const;
+
+ // Value recording support ------------------------------------------------
+
+ /**
+ * Records a value in the histogram, will round this value of to a
+ * precision at or better than the NumberOfSignificantValueDigits specified
+ * at construction time.
+ *
+ * @param value Value to add to the histogram
+ * @return false if the value is larger than the HighestTrackableValue
+ * and can't be recorded, true otherwise.
+ */
+ bool RecordValue(i64 value);
+
+ /**
+ * Records count values in the histogram, will round this value of to a
+ * precision at or better than the NumberOfSignificantValueDigits specified
+ * at construction time.
+ *
+ * @param value Value to add to the histogram
+ * @param count Number of values to add to the histogram
+ * @return false if the value is larger than the HighestTrackableValue
+ * and can't be recorded, true otherwise.
+ */
+ bool RecordValues(i64 value, i64 count);
+
+ /**
+ * Records a value in the histogram and backfill based on an expected
+ * interval. Value will be rounded this to a precision at or better
+ * than the NumberOfSignificantValueDigits specified at contruction time.
+ * This is specifically used for recording latency. If the value is larger
+ * than the expectedInterval then the latency recording system has
+ * experienced co-ordinated omission. This method fills in the values that
+ * would have occured had the client providing the load not been blocked.
+ *
+ * @param value Value to add to the histogram
+ * @param expectedInterval The delay between recording values
+ * @return false if the value is larger than the HighestTrackableValue
+ * and can't be recorded, true otherwise.
+ */
+ bool RecordValueWithExpectedInterval(i64 value, i64 expectedInterval);
+
+ /**
+ * Record a value in the histogram count times. Applies the same correcting
+ * logic as {@link THistogram::RecordValueWithExpectedInterval}.
+ *
+ * @param value Value to add to the histogram
+ * @param count Number of values to add to the histogram
+ * @param expectedInterval The delay between recording values.
+ * @return false if the value is larger than the HighestTrackableValue
+ * and can't be recorded, true otherwise.
+ */
+ bool RecordValuesWithExpectedInterval(
+ i64 value, i64 count, i64 expectedInterval);
+
+ /**
+ * Adds all of the values from rhs to this histogram. Will return the
+ * number of values that are dropped when copying. Values will be dropped
+ * if they around outside of [LowestDiscernibleValue, GetHighestTrackableValue].
+ *
+ * @param rhs Histogram to copy values from.
+ * @return The number of values dropped when copying.
+ */
+ i64 Add(const THistogram& rhs);
+
+ /**
+ * Adds all of the values from rhs to this histogram. Will return the
+ * number of values that are dropped when copying. Values will be dropped
+ * if they around outside of [LowestDiscernibleValue, GetHighestTrackableValue].
+ * Applies the same correcting logic as
+ * {@link THistogram::RecordValueWithExpectedInterval}.
+ *
+ * @param rhs Histogram to copy values from.
+ * @return The number of values dropped when copying.
+ */
+ i64 AddWithExpectedInterval(const THistogram& rhs, i64 expectedInterval);
+
+ // Histogram Data access support ------------------------------------------
+
+ /**
+ * Get the lowest recorded value level in the histogram. If the histogram
+ * has no recorded values, the value returned is undefined.
+ *
+ * @return the Min value recorded in the histogram
+ */
+ i64 GetMin() const;
+
+ /**
+ * Get the highest recorded value level in the histogram. If the histogram
+ * has no recorded values, the value returned is undefined.
+ *
+ * @return the Max value recorded in the histogram
+ */
+ i64 GetMax() const;
+
+ /**
+ * Get the computed mean value of all recorded values in the histogram
+ *
+ * @return the mean value (in value units) of the histogram data
+ */
+ double GetMean() const;
+
+ /**
+ * Get the computed standard deviation of all recorded values in the histogram
+ *
+ * @return the standard deviation (in value units) of the histogram data
+ */
+ double GetStdDeviation() const;
+
+ /**
+ * Get the value at a given percentile.
+ * Note that two values are "equivalent" in this statement if
+ * {@link THistogram::ValuesAreEquivalent} would return true.
+ *
+ * @param percentile The percentile for which to return the associated
+ * value
+ * @return The value that the given percentage of the overall recorded
+ * value entries in the histogram are either smaller than or
+ * equivalent to. When the percentile is 0.0, returns the value
+ * that all value entries in the histogram are either larger than
+ * or equivalent to.
+ */
+ i64 GetValueAtPercentile(double percentile) const;
+
+ /**
+ * Get the count of recorded values at a specific value (to within the
+ * histogram resolution at the value level).
+ *
+ * @param value The value for which to provide the recorded count
+ * @return The total count of values recorded in the histogram within the
+ * value range that is >= GetLowestEquivalentValue(value) and
+ * <= GetHighestEquivalentValue(value)
+ */
+ i64 GetCountAtValue(i64 value) const;
+
+ /**
+ * Determine if two values are equivalent with the histogram's resolution.
+ * Where "equivalent" means that value samples recorded for any two
+ * equivalent values are counted in a common total count.
+ *
+ * @param v1 first value to compare
+ * @param v2 second value to compare
+ * @return True if values are equivalent with the histogram's resolution.
+ */
+ bool ValuesAreEqual(i64 v1, i64 v2) const;
+
+ /**
+ * Get the lowest value that is equivalent to the given value within the
+ * histogram's resolution. Where "equivalent" means that value samples
+ * recorded for any two equivalent values are counted in a common total
+ * count.
+ *
+ * @param value The given value
+ * @return The lowest value that is equivalent to the given value within
+ * the histogram's resolution.
+ */
+ i64 GetLowestEquivalentValue(i64 value) const;
+
+ /**
+ * Get the highest value that is equivalent to the given value within the
+ * histogram's resolution. Where "equivalent" means that value samples
+ * recorded for any two equivalent values are counted in a common total
+ * count.
+ *
+ * @param value The given value
+ * @return The highest value that is equivalent to the given value within
+ * the histogram's resolution.
+ */
+ i64 GetHighestEquivalentValue(i64 value) const;
+
+ /**
+ * Get a value that lies in the middle (rounded up) of the range of values
+ * equivalent the given value. Where "equivalent" means that value samples
+ * recorded for any two equivalent values are counted in a common total
+ * count.
+ *
+ * @param value The given value
+ * @return The value lies in the middle (rounded up) of the range of values
+ * equivalent the given value.
+ */
+ i64 GetMedianEquivalentValue(i64 value) const;
+
+ // misc functions ---------------------------------------------------------
+
+ /**
+ * Reset a histogram to zero - empty out a histogram and re-initialise it.
+ * If you want to re-use an existing histogram, but reset everything back
+ * to zero, this is the routine to use.
+ */
+ void Reset();
+
+ const hdr_histogram* GetHdrHistogramImpl() const {
+ return Data_.Get();
+ }
+
+ private:
+ THolder<hdr_histogram> Data_;
+ IAllocator* Allocator_;
+ };
+}
--
cgit v1.2.3