Top Description Fields Constructors Methods
org.HdrHistogram

public Class AtomicHistogram

extends Histogram
Class Inheritance
Known Direct Subclasses
org.HdrHistogram.Recorder.InternalAtomicHistogram
Imports
java.io.IOException, .ObjectInputStream, java.nio.ByteBuffer, java.util.concurrent.atomic.*, java.util.zip.DataFormatException

A High Dynamic Range (HDR) Histogram using atomic long count type

An AtomicHistogram guarantees lossless recording of values into the histogram even when the histogram is updated by multiple threads. It is important to note though that this lossless recording capability is the only thread-safe behavior provided by AtomicHistogram, and that it is not otherwise synchronized. Specifically, AtomicHistogram does not support auto-resizing, does not support value shift operations, and provides no implicit synchronization that would prevent the contents of the histogram from changing during 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 org.HdrHistogram.SynchronizedHistogram variant, or (recommended) use the Recorder class, which is intended for this purpose.

See package description for org.HdrHistogram for details.

Field Summary

Modifier and TypeField and Description
pack-priv volatile AtomicLongArray
counts

Hides org.HdrHistogram.Histogram.counts.

pack-priv volatile long
totalCount

Hides org.HdrHistogram.Histogram.totalCount.

pack-priv static final AtomicLongFieldUpdater<AtomicHistogram>
totalCountUpdater

Inherited from org.HdrHistogram.Histogram:
normalizingIndexOffset

Constructor Summary

AccessConstructor and Description
public
AtomicHistogram(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 AtomicHistogram given the Highest value to be tracked and a number of significant decimal digits.

public
AtomicHistogram(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 AtomicHistogram given the Lowest and Highest values to be tracked and a number of significant decimal digits.

public
AtomicHistogram(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)

Method Summary

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

Overrides org.HdrHistogram.Histogram._getEstimatedFootprintInBytes.

pack-priv void
addToCountAtIndex(final int index, final long value)

Overrides org.HdrHistogram.Histogram.addToCountAtIndex.

pack-priv void
addToTotalCount(final long value)

Overrides org.HdrHistogram.Histogram.addToTotalCount.

pack-priv void
clearCounts()

Overrides org.HdrHistogram.Histogram.clearCounts.

public AtomicHistogram
copy()

Overrides org.HdrHistogram.Histogram.copy.

Create a copy of this histogram, complete with data and everything.
public AtomicHistogram
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.Histogram.copyCorrectedForCoordinatedOmission.

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

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.Histogram.decodeFromByteBuffer.

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

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.Histogram.decodeFromCompressedByteBuffer.

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

Returns:

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

Hides org.HdrHistogram.Histogram.fromString.

Construct a new AtomicHistogram by decoding it from a String containing a base64 encoded compressed histogram representation.
pack-priv long
getCountAtIndex(final int index)

Overrides org.HdrHistogram.Histogram.getCountAtIndex.

pack-priv long
getCountAtNormalizedIndex(final int index)

Overrides org.HdrHistogram.Histogram.getCountAtNormalizedIndex.

pack-priv int
getNormalizingIndexOffset()

Overrides org.HdrHistogram.Histogram.getNormalizingIndexOffset.

public long
getTotalCount()

Overrides org.HdrHistogram.Histogram.getTotalCount.

Get the total count of all recorded values in the histogram
pack-priv void
incrementCountAtIndex(final int index)

Overrides org.HdrHistogram.Histogram.incrementCountAtIndex.

pack-priv void
incrementTotalCount()

Overrides org.HdrHistogram.Histogram.incrementTotalCount.

private void
readObject(final ObjectInputStream o)

Hides org.HdrHistogram.Histogram.readObject.

pack-priv void
resize(long newHighestTrackableValue)

Overrides org.HdrHistogram.Histogram.resize.

public void
setAutoResize(boolean
autoResize setting
autoResize)

Overrides org.HdrHistogram.AbstractHistogram.setAutoResize.

Control whether or not the histogram can auto-resize and auto-adjust it's highestTrackableValue
pack-priv void
setCountAtIndex(int index, long value)

Overrides org.HdrHistogram.Histogram.setCountAtIndex.

pack-priv void
setCountAtNormalizedIndex(int index, long value)

Overrides org.HdrHistogram.Histogram.setCountAtNormalizedIndex.

pack-priv void
setNormalizingIndexOffset(int normalizingIndexOffset)

Overrides org.HdrHistogram.Histogram.setNormalizingIndexOffset.

pack-priv void
setTotalCount(final long totalCount)

Overrides org.HdrHistogram.Histogram.setTotalCount.

pack-priv void
shiftNormalizingIndexByOffset(int offsetToAdd, boolean lowestHalfBucketPopulated, double newIntegerToDoubleValueConversionRatio)

Overrides org.HdrHistogram.Histogram.shiftNormalizingIndexByOffset.

public boolean
supportsAutoResize()

Overrides org.HdrHistogram.AbstractHistogram.supportsAutoResize.

Indicate whether or not the histogram is capable of supporting auto-resize functionality.
Inherited from org.HdrHistogram.Histogram:
setIntegerToDoubleValueConversionRatio

Field Detail

countsback to summary
pack-priv volatile AtomicLongArray counts

Hides org.HdrHistogram.Histogram.counts.

totalCountback to summary
pack-priv volatile long totalCount

Hides org.HdrHistogram.Histogram.totalCount.

totalCountUpdaterback to summary
pack-priv static final AtomicLongFieldUpdater<AtomicHistogram> totalCountUpdater

Constructor Detail

AtomicHistogramback to summary
public AtomicHistogram(final long highestTrackableValue, final int numberOfSignificantValueDigits)

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

AtomicHistogramback to summary
public AtomicHistogram(final long lowestDiscernibleValue, final long highestTrackableValue, final int numberOfSignificantValueDigits)

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

AtomicHistogramback to summary
public AtomicHistogram(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

Method Detail

_getEstimatedFootprintInBytesback to summary
pack-priv int _getEstimatedFootprintInBytes()

Overrides org.HdrHistogram.Histogram._getEstimatedFootprintInBytes.

Annotations
@Override
addToCountAtIndexback to summary
pack-priv void addToCountAtIndex(final int index, final long value)

Overrides org.HdrHistogram.Histogram.addToCountAtIndex.

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

Overrides org.HdrHistogram.Histogram.addToTotalCount.

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

Overrides org.HdrHistogram.Histogram.clearCounts.

Annotations
@Override
copyback to summary
public AtomicHistogram copy()

Overrides org.HdrHistogram.Histogram.copy.

Doc from org.HdrHistogram.AbstractHistogram.copy.

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

Returns:AtomicHistogram

A distinct copy of this histogram.

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

Overrides org.HdrHistogram.Histogram.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:AtomicHistogram

a copy of this histogram, corrected for coordinated omission.

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

Hides org.HdrHistogram.Histogram.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:AtomicHistogram

The newly constructed histogram

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

Hides org.HdrHistogram.Histogram.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:AtomicHistogram

The newly constructed histogram

Exceptions
DataFormatException:
on error parsing/decompressing the buffer
fromStringback to summary
public static AtomicHistogram fromString(final String base64CompressedHistogramString) throws DataFormatException

Hides org.HdrHistogram.Histogram.fromString.

Construct a new AtomicHistogram 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:AtomicHistogram

A AtomicHistogram decoded from the string

Exceptions
DataFormatException:
on error parsing/decompressing the input
getCountAtIndexback to summary
pack-priv long getCountAtIndex(final int index)

Overrides org.HdrHistogram.Histogram.getCountAtIndex.

Annotations
@Override
getCountAtNormalizedIndexback to summary
pack-priv long getCountAtNormalizedIndex(final int index)

Overrides org.HdrHistogram.Histogram.getCountAtNormalizedIndex.

Annotations
@Override
getNormalizingIndexOffsetback to summary
pack-priv int getNormalizingIndexOffset()

Overrides org.HdrHistogram.Histogram.getNormalizingIndexOffset.

Annotations
@Override
getTotalCountback to summary
public long getTotalCount()

Overrides org.HdrHistogram.Histogram.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
incrementCountAtIndexback to summary
pack-priv void incrementCountAtIndex(final int index)

Overrides org.HdrHistogram.Histogram.incrementCountAtIndex.

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

Overrides org.HdrHistogram.Histogram.incrementTotalCount.

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

Hides org.HdrHistogram.Histogram.readObject.

resizeback to summary
pack-priv void resize(long newHighestTrackableValue)

Overrides org.HdrHistogram.Histogram.resize.

Annotations
@Override
setAutoResizeback to summary
public void setAutoResize(boolean autoResize)

Overrides org.HdrHistogram.AbstractHistogram.setAutoResize.

Doc from org.HdrHistogram.AbstractHistogram.setAutoResize.

Control whether or not the histogram can auto-resize and auto-adjust it's highestTrackableValue

Parameters
autoResize:boolean

autoResize setting

Annotations
@Override
setCountAtIndexback to summary
pack-priv void setCountAtIndex(int index, long value)

Overrides org.HdrHistogram.Histogram.setCountAtIndex.

Annotations
@Override
setCountAtNormalizedIndexback to summary
pack-priv void setCountAtNormalizedIndex(int index, long value)

Overrides org.HdrHistogram.Histogram.setCountAtNormalizedIndex.

Annotations
@Override
setNormalizingIndexOffsetback to summary
pack-priv void setNormalizingIndexOffset(int normalizingIndexOffset)

Overrides org.HdrHistogram.Histogram.setNormalizingIndexOffset.

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

Overrides org.HdrHistogram.Histogram.setTotalCount.

Annotations
@Override
shiftNormalizingIndexByOffsetback to summary
pack-priv void shiftNormalizingIndexByOffset(int offsetToAdd, boolean lowestHalfBucketPopulated, double newIntegerToDoubleValueConversionRatio)

Overrides org.HdrHistogram.Histogram.shiftNormalizingIndexByOffset.

Annotations
@Override
supportsAutoResizeback to summary
public boolean supportsAutoResize()

Overrides org.HdrHistogram.AbstractHistogram.supportsAutoResize.

Doc from org.HdrHistogram.AbstractHistogram.supportsAutoResize.

Indicate whether or not the histogram is capable of supporting auto-resize functionality. Note that this is an indication that enabling auto-resize by calling setAutoResize() is allowed, and NOT that the histogram will actually auto-resize. Use isAutoResize() to determine if the histogram is in auto-resize mode.

Returns:boolean

autoResize setting

Annotations
@Override