org.HdrHistogram
Class ConcurrentDoubleHistogram

java.lang.Object
  org.HdrHistogram.EncodableHistogram
      org.HdrHistogram.DoubleHistogram
          org.HdrHistogram.ConcurrentDoubleHistogram

All Implemented Interfaces:

Serializable

public class ConcurrentDoubleHistogram
extends DoubleHistogram

A floating point values High Dynamic Range (HDR) Histogram that supports safe concurrent recording operations.

A ConcurrentDoubleHistogram is a variant of DoubleHistogram that guarantees lossless recording of values into the hsitogram even when the histogram is updated by mutliple threads, and supports auto-resize and auto-ranging operations that may occur concurrently as a result of recording operations.

It is important to note that concurrent recording, auto-sizing, and value shifting are the only thread-safe behaviors provided by ConcurrentDoubleHistogram, and that it is not otherwise synchronized. Specifically, ConcurrentDoubleHistogram provides no implicit synchronization that would prevent the contents of the histogram from changing during queries, iterations, copies, or addition operations on the histogram. Callers wishing to make potentially concurrent, multi-threaded updates that would safely work in the presence of queries, copies, or additions of histogram objects should either take care to externally synchronize and/or order their access, use the SynchronizedDoubleHistogram variant, or (recommended) use the DoubleRecorder class, which is intended for this purpose.

ConcurrentDoubleHistogram supports the recording and analyzing sampled data value counts across a configurable dynamic range of floating point (double) values, with configurable value precision within the range. Dynamic range is expressed as a ratio between the hightes and lowest non-zero values trackable within the histogram at any given time. Value precision is expressed as the number of significant [decimal] 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.

Auto-ranging: Unlike integer value based histograms, the specific value range tracked by a ConcurrentDoubleHistogram is not specified upfront. Only the dynamic range of values that the histogram can cover is (optionally) specified. E.g. When a ConcurrentDoubleHistogram is created to track a dynamic range of 3600000000000 (enoygh to track values from a nanosecond to an hour), values could be recorded into into it in any consistent unit of time as long as the ratio between the highest and lowest non-zero values stays within the specified dynamic range, so recording in units of nanoseconds (1.0 thru 3600000000000.0), milliseconds (0.000001 thru 3600000.0) seconds (0.000000001 thru 3600.0), hours (1/3.6E12 thru 1.0) will all work just as well.

Auto-resizing: When constructed with no specified dynamic range (or when auto-resize is turned on with DoubleHistogram.setAutoResize(boolean)) a ConcurrentDoubleHistogram will auto-resize its dynamic range to include recorded values as they are encountered. Note that recording calls that cause auto-resizing may take longer to execute, as resizing incurrs allocation and copying of internal data structures.

Attempts to record non-zero values that range outside of the specified dynamic range (or exceed the limits of of dynamic range when auto-resizing) may results in ArrayIndexOutOfBoundsException exceptions, either due to overflow or underflow conditions. These exceptions will only be thrown if recording the value would have resulted in discarding or losing the required value precision of values already recorded in the histogram.

See package description for org.HdrHistogram for details.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.HdrHistogram.DoubleHistogram

DoubleHistogram.AllValues, DoubleHistogram.LinearBucketValues, DoubleHistogram.LogarithmicBucketValues, DoubleHistogram.Percentiles, DoubleHistogram.RecordedValues

Constructor Summary

ConcurrentDoubleHistogram(ConcurrentDoubleHistogram source)
Construct a ConcurrentDoubleHistogram with the same range settings as a given source, duplicating the source's start/end timestamps (but NOT it's contents)

ConcurrentDoubleHistogram(int numberOfSignificantValueDigits)
Construct a new auto-resizing DoubleHistogram using a precision stated as a number of significant decimal digits.

ConcurrentDoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits)
Construct a new DoubleHistogram with the specified dynamic range (provided in highestToLowestValueRatio) and using a precision stated as a number of significant decimal digits.

Method Summary

Methods inherited from class org.HdrHistogram.DoubleHistogram

add, addWhileCorrectingForCoordinatedOmission, allValues, copy, copyCorrectedForCoordinatedOmission, copyInto, copyIntoCorrectedForCoordinatedOmission, decodeFromByteBuffer, decodeFromByteBuffer, decodeFromCompressedByteBuffer, decodeFromCompressedByteBuffer, encodeIntoByteBuffer, encodeIntoCompressedByteBuffer, encodeIntoCompressedByteBuffer, equals, getCountAtValue, getCountBetweenValues, getEndTimeStamp, getEstimatedFootprintInBytes, getHighestToLowestValueRatio, getIntegerToDoubleValueConversionRatio, getMaxValue, getMaxValueAsDouble, getMean, getMinNonZeroValue, getMinValue, getNeededByteBufferCapacity, getNumberOfSignificantValueDigits, getPercentileAtOrBelowValue, getStartTimeStamp, getStdDeviation, getTotalCount, getValueAtPercentile, highestEquivalentValue, isAutoResize, linearBucketValues, logarithmicBucketValues, lowestEquivalentValue, medianEquivalentValue, nextNonEquivalentValue, outputPercentileDistribution, outputPercentileDistribution, outputPercentileDistribution, percentiles, recordedValues, recordValue, recordValueWithCount, recordValueWithExpectedInterval, reset, setAutoResize, setEndTimeStamp, setStartTimeStamp, sizeOfEquivalentValueRange, subtract, valuesAreEquivalent

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ConcurrentDoubleHistogram

public ConcurrentDoubleHistogram(int numberOfSignificantValueDigits)

Construct a new auto-resizing DoubleHistogram using a precision stated as a number of significant decimal digits.

Parameters:

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.

ConcurrentDoubleHistogram

public ConcurrentDoubleHistogram(long highestToLowestValueRatio,
                                 int numberOfSignificantValueDigits)

Construct a new DoubleHistogram with the specified dynamic range (provided in highestToLowestValueRatio) and using a precision stated as a number of significant decimal digits.

Parameters:

highestToLowestValueRatio - specifies the dynamic range to use

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.

ConcurrentDoubleHistogram

public ConcurrentDoubleHistogram(ConcurrentDoubleHistogram source)

Construct a ConcurrentDoubleHistogram with the same range settings as a given source, duplicating the source's start/end timestamps (but NOT it's contents)

Parameters:

source - The source histogram to duplicate