public class PackedConcurrentDoubleHistogram extends ConcurrentDoubleHistogram
A PackedConcurrentDoubleHistogram
is a variant of DoubleHistogram
that guarantees
lossless recording of values into the histogram even when the histogram is updated by multiple threads, and
supports auto-resize and auto-ranging operations that may occur concurrently as a result of recording operations.
PackedConcurrentDoubleHistogram
tracks value counts in a packed internal representation optimized
for typical histogram recoded values are sparse in the value range and tend to be incremented in small unit counts.
This packed representation tends to require significantly smaller amounts of stoarge when compared to unpacked
representations, but can incur additional recording cost due to resizing and repacking operations that may
occur as previously unrecorded values are encountered.
It is important to note that concurrent recording, auto-sizing, and value shifting are the only thread-safe behaviors
provided by PackedConcurrentDoubleHistogram
, and that it is not otherwise synchronized. Specifically, PackedConcurrentDoubleHistogram
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 DoubleRecorder
or SingleWriterDoubleRecorder
which are intended for this purpose.
PackedConcurrentDoubleHistogram
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 highest 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 PackedConcurrentDoubleHistogram
is not specified upfront. Only the dynamic range of values that the histogram can cover is
(optionally) specified. E.g. When a PackedConcurrentDoubleHistogram
is created to track a dynamic range of
3600000000000 (enough 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 PackedConcurrentDoubleHistogram
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 incurs 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.
DoubleHistogram.AllValues, DoubleHistogram.LinearBucketValues, DoubleHistogram.LogarithmicBucketValues, DoubleHistogram.Percentiles, DoubleHistogram.RecordedValues
Constructor and Description |
---|
PackedConcurrentDoubleHistogram(DoubleHistogram source)
Construct a
PackedConcurrentDoubleHistogram with the same range settings as a given source,
duplicating the source's start/end timestamps (but NOT it's contents) |
PackedConcurrentDoubleHistogram(int numberOfSignificantValueDigits)
Construct a new auto-resizing DoubleHistogram using a precision stated as a number of significant decimal
digits.
|
PackedConcurrentDoubleHistogram(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. |
Modifier and Type | Method and Description |
---|---|
static PackedConcurrentDoubleHistogram |
decodeFromByteBuffer(ByteBuffer buffer,
long minBarForHighestToLowestValueRatio)
Construct a new ConcurrentDoubleHistogram by decoding it from a ByteBuffer.
|
static PackedConcurrentDoubleHistogram |
decodeFromCompressedByteBuffer(ByteBuffer buffer,
long minBarForHighestToLowestValueRatio)
Construct a new ConcurrentDoubleHistogram by decoding it from a compressed form in a ByteBuffer.
|
add, addWhileCorrectingForCoordinatedOmission, allValues, copy, copyCorrectedForCoordinatedOmission, copyInto, copyIntoCorrectedForCoordinatedOmission, decodeFromByteBuffer, decodeFromCompressedByteBuffer, encodeIntoByteBuffer, encodeIntoCompressedByteBuffer, encodeIntoCompressedByteBuffer, equals, fromString, getCountAtValue, getCountBetweenValues, getEndTimeStamp, getEstimatedFootprintInBytes, getHighestToLowestValueRatio, getIntegerToDoubleValueConversionRatio, getMaxValue, getMaxValueAsDouble, getMean, getMinNonZeroValue, getMinValue, getNeededByteBufferCapacity, getNumberOfSignificantValueDigits, getPercentileAtOrBelowValue, getStartTimeStamp, getStdDeviation, getTag, getTotalCount, getValueAtPercentile, hashCode, highestEquivalentValue, isAutoResize, linearBucketValues, logarithmicBucketValues, lowestEquivalentValue, medianEquivalentValue, nextNonEquivalentValue, outputPercentileDistribution, outputPercentileDistribution, outputPercentileDistribution, percentiles, recordedValues, recordValue, recordValueWithCount, recordValueWithExpectedInterval, reset, setAutoResize, setEndTimeStamp, setStartTimeStamp, setTag, sizeOfEquivalentValueRange, subtract, valuesAreEquivalent
public PackedConcurrentDoubleHistogram(int numberOfSignificantValueDigits)
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.public PackedConcurrentDoubleHistogram(long highestToLowestValueRatio, int numberOfSignificantValueDigits)
highestToLowestValueRatio
)
and using a precision stated as a number of significant decimal digits.highestToLowestValueRatio
- specifies the dynamic range to usenumberOfSignificantValueDigits
- 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.public PackedConcurrentDoubleHistogram(DoubleHistogram source)
PackedConcurrentDoubleHistogram
with the same range settings as a given source,
duplicating the source's start/end timestamps (but NOT it's contents)source
- The source histogram to duplicatepublic static PackedConcurrentDoubleHistogram decodeFromByteBuffer(ByteBuffer buffer, long minBarForHighestToLowestValueRatio)
buffer
- The buffer to decode fromminBarForHighestToLowestValueRatio
- Force highestTrackableValue to be set at least this highpublic static PackedConcurrentDoubleHistogram decodeFromCompressedByteBuffer(ByteBuffer buffer, long minBarForHighestToLowestValueRatio) throws DataFormatException
buffer
- The buffer to decode fromminBarForHighestToLowestValueRatio
- Force highestTrackableValue to be set at least this highDataFormatException
- on error parsing/decompressing the bufferCopyright © 2019. All rights reserved.