Top Description Inners Fields Constructors Methods
org.HdrHistogram

public Class PackedConcurrentHistogram

extends ConcurrentHistogram
Class Inheritance
Known Direct Subclasses
org.HdrHistogram.Recorder.InternalPackedConcurrentHistogram
Imports
org.HdrHistogram.packedarray.ConcurrentPackedLongArray, java.io.IOException, .ObjectInputStream, .Serializable, java.nio.ByteBuffer, java.util.zip.DataFormatException

An integer values High Dynamic Range (HDR) Histogram that uses a packed internal representation and supports safe concurrent recording operations.

A PackedConcurrentHistogram guarantees lossless recording of values into the histogram even when the histogram is updated by multiple threads, and supports auto-resize and shift operations that may result from or occur concurrently with other recording operations.

PackedConcurrentHistogram 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 PackedConcurrentHistogram, and that it is not otherwise synchronized. Specifically, PackedConcurrentHistogram 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 Recorder or SingleWriterRecorder which are intended for this purpose.

Auto-resizing: When constructed with no specified value range range (or when auto-resize is turned on with Histogram#setAutoResize) a PackedConcurrentHistogram 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.

See package description for org.HdrHistogram for details.

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
PackedConcurrentHistogram.ConcurrentPackedArrayWithNormalizingOffset

Field Summary

Inherited from org.HdrHistogram.ConcurrentHistogram:
activeCountsinactiveCountstotalCounttotalCountUpdaterwrp

Constructor Summary

AccessConstructor and Description
public
PackedConcurrentHistogram(final int
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.
numberOfSignificantValueDigits)

Construct an auto-resizing ConcurrentHistogram with a lowest discernible value of 1 and an auto-adjusting highestTrackableValue.

public
PackedConcurrentHistogram(final long
The highest value to be tracked by the histogram. Must be a positive integer that is >= 2.
highestTrackableValue, final int
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.
numberOfSignificantValueDigits)

Construct a ConcurrentHistogram given the Highest value to be tracked and a number of significant decimal digits.

public
PackedConcurrentHistogram(final long
The lowest value that can be tracked (distinguished from 0) by the histogram. Must be a positive integer that is >= 1. May be internally rounded down to nearest power of 2.
lowestDiscernibleValue, final long
The highest value to be tracked by the histogram. Must be a positive integer that is >= (2 * lowestDiscernibleValue).
highestTrackableValue, final int
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.
numberOfSignificantValueDigits)

Construct a ConcurrentHistogram given the Lowest and Highest values to be tracked and a number of significant decimal digits.

public
PackedConcurrentHistogram(final AbstractHistogram
The source histogram to duplicate
source)

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

pack-priv
PackedConcurrentHistogram(final AbstractHistogram source, boolean allocateCountsArray)

pack-priv
PackedConcurrentHistogram(final long lowestDiscernibleValue, final long highestTrackableValue, final int numberOfSignificantValueDigits, boolean allocateCountsArray)

Method Summary

Modifier and TypeMethod and Description
pack-priv int
_getEstimatedFootprintInBytes()

Overrides org.HdrHistogram.ConcurrentHistogram._getEstimatedFootprintInBytes.

pack-priv void
addToTotalCount(final long value)

Overrides org.HdrHistogram.ConcurrentHistogram.addToTotalCount.

pack-priv ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset
allocateArray(int length, int normalizingIndexOffset)

Overrides org.HdrHistogram.ConcurrentHistogram.allocateArray.

pack-priv void
clearCounts()

Overrides org.HdrHistogram.ConcurrentHistogram.clearCounts.

public PackedConcurrentHistogram
copy()

Overrides org.HdrHistogram.ConcurrentHistogram.copy.

Create a copy of this histogram, complete with data and everything.
public PackedConcurrentHistogram
copyCorrectedForCoordinatedOmission(final long
If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
expectedIntervalBetweenValueSamples)

Overrides org.HdrHistogram.ConcurrentHistogram.copyCorrectedForCoordinatedOmission.

Get a copy of this histogram, corrected for coordinated omission.
public static PackedConcurrentHistogram

Returns:

The newly constructed histogram
decodeFromByteBuffer(final ByteBuffer
The buffer to decode from
buffer, final long
Force highestTrackableValue to be set at least this high
minBarForHighestTrackableValue)

Hides org.HdrHistogram.ConcurrentHistogram.decodeFromByteBuffer.

Construct a new histogram by decoding it from a ByteBuffer.
public static PackedConcurrentHistogram

Returns:

The newly constructed histogram
decodeFromCompressedByteBuffer(final ByteBuffer
The buffer to decode from
buffer, final long
Force highestTrackableValue to be set at least this high
minBarForHighestTrackableValue)

Hides org.HdrHistogram.ConcurrentHistogram.decodeFromCompressedByteBuffer.

Construct a new histogram by decoding it from a compressed form in a ByteBuffer.
pack-priv synchronized void
fillBufferFromCountsArray(final ByteBuffer buffer)

Overrides org.HdrHistogram.ConcurrentHistogram.fillBufferFromCountsArray.

public static PackedConcurrentHistogram

Returns:

A ConcurrentHistogram decoded from the string
fromString(final String
A string containing a base64 encoding of a compressed histogram
base64CompressedHistogramString)

Hides org.HdrHistogram.ConcurrentHistogram.fromString.

Construct a new ConcurrentHistogram by decoding it from a String containing a base64 encoded compressed histogram representation.
public long
getTotalCount()

Overrides org.HdrHistogram.ConcurrentHistogram.getTotalCount.

Get the total count of all recorded values in the histogram
pack-priv void
incrementTotalCount()

Overrides org.HdrHistogram.ConcurrentHistogram.incrementTotalCount.

private void
readObject(final ObjectInputStream o)

Hides org.HdrHistogram.ConcurrentHistogram.readObject.

pack-priv void
setTotalCount(final long totalCount)

Overrides org.HdrHistogram.ConcurrentHistogram.setTotalCount.

Inherited from org.HdrHistogram.ConcurrentHistogram:
addToCountAtIndexcopyInactiveCountsContentsOnResizegetCountAtIndexgetCountAtNormalizedIndexgetNormalizingIndexOffsetincrementCountAtIndexrecordConvertedDoubleValuerecordConvertedDoubleValueWithCountresizesetAutoResizesetCountAtIndexsetCountAtNormalizedIndexsetIntegerToDoubleValueConversionRatiosetNormalizingIndexOffsetshiftNormalizingIndexByOffset

Constructor Detail

PackedConcurrentHistogramback to summary
public PackedConcurrentHistogram(final int numberOfSignificantValueDigits)

Construct an auto-resizing ConcurrentHistogram with a lowest discernible value of 1 and an auto-adjusting highestTrackableValue. Can auto-resize up to track values up to (Long.MAX_VALUE / 2).

Parameters
numberOfSignificantValueDigits:int

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.

PackedConcurrentHistogramback to summary
public PackedConcurrentHistogram(final long highestTrackableValue, final int numberOfSignificantValueDigits)

Construct a ConcurrentHistogram 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.

Parameters
highestTrackableValue:long

The highest value to be tracked by the histogram. Must be a positive integer that is >= 2.

numberOfSignificantValueDigits:int

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.

PackedConcurrentHistogramback to summary
public PackedConcurrentHistogram(final long lowestDiscernibleValue, final long highestTrackableValue, final int numberOfSignificantValueDigits)

Construct a ConcurrentHistogram given the Lowest and Highest values to be tracked and a number of significant decimal digits. Providing a lowestDiscernibleValue is useful is 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.

Parameters
lowestDiscernibleValue:long

The lowest value that can be tracked (distinguished from 0) by the histogram. Must be a positive integer that is >= 1. May be internally rounded down to nearest power of 2.

highestTrackableValue:long

The highest value to be tracked by the histogram. Must be a positive integer that is >= (2 * lowestDiscernibleValue).

numberOfSignificantValueDigits:int

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.

PackedConcurrentHistogramback to summary
public PackedConcurrentHistogram(final AbstractHistogram source)

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

Parameters
source:AbstractHistogram

The source histogram to duplicate

PackedConcurrentHistogramback to summary
pack-priv PackedConcurrentHistogram(final AbstractHistogram source, boolean allocateCountsArray)
PackedConcurrentHistogramback to summary
pack-priv PackedConcurrentHistogram(final long lowestDiscernibleValue, final long highestTrackableValue, final int numberOfSignificantValueDigits, boolean allocateCountsArray)

Method Detail

_getEstimatedFootprintInBytesback to summary
pack-priv int _getEstimatedFootprintInBytes()

Overrides org.HdrHistogram.ConcurrentHistogram._getEstimatedFootprintInBytes.

Annotations
@Override
addToTotalCountback to summary
pack-priv void addToTotalCount(final long value)

Overrides org.HdrHistogram.ConcurrentHistogram.addToTotalCount.

Annotations
@Override
allocateArrayback to summary
pack-priv ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset allocateArray(int length, int normalizingIndexOffset)

Overrides org.HdrHistogram.ConcurrentHistogram.allocateArray.

Annotations
@Override
clearCountsback to summary
pack-priv void clearCounts()

Overrides org.HdrHistogram.ConcurrentHistogram.clearCounts.

Annotations
@Override
copyback to summary
public PackedConcurrentHistogram copy()

Overrides org.HdrHistogram.ConcurrentHistogram.copy.

Doc from org.HdrHistogram.AbstractHistogram.copy.

Create a copy of this histogram, complete with data and everything.

Returns:PackedConcurrentHistogram

A distinct copy of this histogram.

Annotations
@Override
copyCorrectedForCoordinatedOmissionback to summary
public PackedConcurrentHistogram copyCorrectedForCoordinatedOmission(final long expectedIntervalBetweenValueSamples)

Overrides org.HdrHistogram.ConcurrentHistogram.copyCorrectedForCoordinatedOmission.

Doc from org.HdrHistogram.AbstractHistogram.copyCorrectedForCoordinatedOmission.

Get a copy of this histogram, corrected for coordinated omission.

To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, the new histogram will include an auto-generated additional series of decreasingly-smaller (down to the expectedIntervalBetweenValueSamples) value records for each count found in the current histogram that is larger than the expectedIntervalBetweenValueSamples.

Note

This is a post-correction method, as opposed to the at-recording correction method provided by recordValueWithExpectedInterval. The two methods are mutually exclusive, and only one of the two should be be used on a given data set to correct for the same coordinated omission issue. by

See notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.

Parameters
expectedIntervalBetweenValueSamples:long

If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples

Returns:PackedConcurrentHistogram

a copy of this histogram, corrected for coordinated omission.

Annotations
@Override
decodeFromByteBufferback to summary
public static PackedConcurrentHistogram decodeFromByteBuffer(final ByteBuffer buffer, final long minBarForHighestTrackableValue)

Hides org.HdrHistogram.ConcurrentHistogram.decodeFromByteBuffer.

Construct a new histogram by decoding it from a ByteBuffer.

Parameters
buffer:ByteBuffer

The buffer to decode from

minBarForHighestTrackableValue:long

Force highestTrackableValue to be set at least this high

Returns:PackedConcurrentHistogram

The newly constructed histogram

decodeFromCompressedByteBufferback to summary
public static PackedConcurrentHistogram decodeFromCompressedByteBuffer(final ByteBuffer buffer, final long minBarForHighestTrackableValue) throws DataFormatException

Hides org.HdrHistogram.ConcurrentHistogram.decodeFromCompressedByteBuffer.

Construct a new histogram by decoding it from a compressed form in a ByteBuffer.

Parameters
buffer:ByteBuffer

The buffer to decode from

minBarForHighestTrackableValue:long

Force highestTrackableValue to be set at least this high

Returns:PackedConcurrentHistogram

The newly constructed histogram

Exceptions
DataFormatException:
on error parsing/decompressing the buffer
fillBufferFromCountsArrayback to summary
pack-priv synchronized void fillBufferFromCountsArray(final ByteBuffer buffer)

Overrides org.HdrHistogram.ConcurrentHistogram.fillBufferFromCountsArray.

Annotations
@Override
fromStringback to summary
public static PackedConcurrentHistogram fromString(final String base64CompressedHistogramString) throws DataFormatException

Hides org.HdrHistogram.ConcurrentHistogram.fromString.

Construct a new ConcurrentHistogram by decoding it from a String containing a base64 encoded compressed histogram representation.

Parameters
base64CompressedHistogramString:String

A string containing a base64 encoding of a compressed histogram

Returns:PackedConcurrentHistogram

A ConcurrentHistogram decoded from the string

Exceptions
DataFormatException:
on error parsing/decompressing the input
getTotalCountback to summary
public long getTotalCount()

Overrides org.HdrHistogram.ConcurrentHistogram.getTotalCount.

Doc from org.HdrHistogram.AbstractHistogram.getTotalCount.

Get the total count of all recorded values in the histogram

Returns:long

the total count of all recorded values in the histogram

Annotations
@Override
incrementTotalCountback to summary
pack-priv void incrementTotalCount()

Overrides org.HdrHistogram.ConcurrentHistogram.incrementTotalCount.

Annotations
@Override
readObjectback to summary
private void readObject(final ObjectInputStream o) throws IOException, ClassNotFoundException

Hides org.HdrHistogram.ConcurrentHistogram.readObject.

setTotalCountback to summary
pack-priv void setTotalCount(final long totalCount)

Overrides org.HdrHistogram.ConcurrentHistogram.setTotalCount.

Annotations
@Override
org.HdrHistogram back to summary

pack-priv Class PackedConcurrentHistogram.ConcurrentPackedArrayWithNormalizingOffset

extends Object
implements ConcurrentArrayWithNormalizingOffset, Serializable
Class Inheritance
  • java.lang.Object
  • org.HdrHistogram.PackedConcurrentHistogram.ConcurrentPackedArrayWithNormalizingOffset
All Implemented Interfaces
java.io.Serializable, org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset

Field Summary

Modifier and TypeField and Description
private double
doubleToIntegerValueConversionRatio

private int
normalizingIndexOffset

private ConcurrentPackedLongArray
packedCounts

Constructor Summary

AccessConstructor and Description
pack-priv
ConcurrentPackedArrayWithNormalizingOffset(int length, int normalizingIndexOffset)

Method Summary

Modifier and TypeMethod and Description
public void
atomicAdd(int index, long valueToAdd)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.atomicAdd.

public void
atomicIncrement(int index)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.atomicIncrement.

public long
get(int index)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.get.

public double
getDoubleToIntegerValueConversionRatio()

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.getDoubleToIntegerValueConversionRatio.

public int
getEstimatedFootprintInBytes()

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.getEstimatedFootprintInBytes.

public int
getNormalizingIndexOffset()

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.getNormalizingIndexOffset.

public void
lazySet(int index, long newValue)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.lazySet.

public int
length()

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.length.

public void
setDoubleToIntegerValueConversionRatio(double doubleToIntegerValueConversionRatio)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.setDoubleToIntegerValueConversionRatio.

public void
setNormalizingIndexOffset(int normalizingIndexOffset)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.setNormalizingIndexOffset.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

doubleToIntegerValueConversionRatioback to summary
private double doubleToIntegerValueConversionRatio
normalizingIndexOffsetback to summary
private int normalizingIndexOffset
packedCountsback to summary
private ConcurrentPackedLongArray packedCounts

Constructor Detail

ConcurrentPackedArrayWithNormalizingOffsetback to summary
pack-priv ConcurrentPackedArrayWithNormalizingOffset(int length, int normalizingIndexOffset)

Method Detail

atomicAddback to summary
public void atomicAdd(int index, long valueToAdd)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.atomicAdd.

Annotations
@Override
atomicIncrementback to summary
public void atomicIncrement(int index)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.atomicIncrement.

Annotations
@Override
getback to summary
public long get(int index)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.get.

Annotations
@Override
getDoubleToIntegerValueConversionRatioback to summary
public double getDoubleToIntegerValueConversionRatio()

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.getDoubleToIntegerValueConversionRatio.

getEstimatedFootprintInBytesback to summary
public int getEstimatedFootprintInBytes()

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.getEstimatedFootprintInBytes.

Annotations
@Override
getNormalizingIndexOffsetback to summary
public int getNormalizingIndexOffset()

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.getNormalizingIndexOffset.

lazySetback to summary
public void lazySet(int index, long newValue)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.lazySet.

Annotations
@Override
lengthback to summary
public int length()

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.length.

Annotations
@Override
setDoubleToIntegerValueConversionRatioback to summary
public void setDoubleToIntegerValueConversionRatio(double doubleToIntegerValueConversionRatio)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.setDoubleToIntegerValueConversionRatio.

setNormalizingIndexOffsetback to summary
public void setNormalizingIndexOffset(int normalizingIndexOffset)

Implements org.HdrHistogram.ConcurrentHistogram.ConcurrentArrayWithNormalizingOffset.setNormalizingIndexOffset.