Class SynchronizedHistogram
- java.lang.Object
-
- org.HdrHistogram.EncodableHistogram
-
- org.HdrHistogram.AbstractHistogramBase
-
- org.HdrHistogram.AbstractHistogram
-
- org.HdrHistogram.Histogram
-
- org.HdrHistogram.SynchronizedHistogram
-
- All Implemented Interfaces:
java.io.Serializable
,ValueRecorder
public class SynchronizedHistogram extends Histogram
An integer values High Dynamic Range (HDR) Histogram that is synchronized as a whole
A
SynchronizedHistogram
is a variant ofHistogram
that is synchronized as a whole, such that queries, copying, and addition operations are atomic with relation to modification on theSynchronizedHistogram
, and such that external accessors (e.g. iterations on the histogram data) that synchronize on theSynchronizedHistogram
instance can safely assume that no modifications to the histogram data occur within their synchronized block.It is important to note that synchronization can result in blocking recoding calls. If non-blocking recoding operations are required, consider using
ConcurrentHistogram
,AtomicHistogram
, or (recommended)Recorder
orSingleWriterRecorder
which were intended for concurrent operations.See package description for
org.HdrHistogram
andHistogram
for more details.- See Also:
- Serialized Form
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class org.HdrHistogram.AbstractHistogram
AbstractHistogram.AllValues, AbstractHistogram.LinearBucketValues, AbstractHistogram.LogarithmicBucketValues, AbstractHistogram.Percentiles, AbstractHistogram.RecordedValues
-
-
Field Summary
-
Fields inherited from class org.HdrHistogram.Histogram
counts, normalizingIndexOffset, totalCount
-
Fields inherited from class org.HdrHistogram.AbstractHistogram
leadingZeroCountBase, maxValue, minNonZeroValue, subBucketHalfCount, subBucketHalfCountMagnitude, subBucketMask, unitMagnitude, unitMagnitudeMask
-
Fields inherited from class org.HdrHistogram.AbstractHistogramBase
autoResize, bucketCount, constructionIdentityCount, countsArrayLength, doubleToIntegerValueConversionRatio, endTimeStampMsec, highestTrackableValue, identity, integerToDoubleValueConversionRatio, intermediateUncompressedByteArray, intermediateUncompressedByteBuffer, lowestDiscernibleValue, numberOfSignificantValueDigits, percentileIterator, recordedValuesIterator, startTimeStampMsec, subBucketCount, tag, wordSizeInBytes
-
-
Constructor Summary
Constructors Constructor Description SynchronizedHistogram(int numberOfSignificantValueDigits)
Construct an auto-resizing SynchronizedHistogram with a lowest discernible value of 1 and an auto-adjusting highestTrackableValue.SynchronizedHistogram(long highestTrackableValue, int numberOfSignificantValueDigits)
Construct a SynchronizedHistogram given the Highest value to be tracked and a number of significant decimal digits.SynchronizedHistogram(long lowestDiscernibleValue, long highestTrackableValue, int numberOfSignificantValueDigits)
Construct a SynchronizedHistogram given the Lowest and Highest values to be tracked and a number of significant decimal digits.SynchronizedHistogram(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)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
add(AbstractHistogram otherHistogram)
Add the contents of another histogram to this one.void
addWhileCorrectingForCoordinatedOmission(AbstractHistogram fromHistogram, long expectedIntervalBetweenValueSamples)
Add the contents of another histogram to this one, while correcting the incoming data for coordinated omission.AbstractHistogram.AllValues
allValues()
Provide a means of iterating through all histogram values using the finest granularity steps supported by the underlying representation.SynchronizedHistogram
copy()
Create a copy of this histogram, complete with data and everything.SynchronizedHistogram
copyCorrectedForCoordinatedOmission(long expectedIntervalBetweenValueSamples)
Get a copy of this histogram, corrected for coordinated omission.void
copyInto(AbstractHistogram targetHistogram)
Copy this histogram into the target histogram, overwriting it's contents.void
copyIntoCorrectedForCoordinatedOmission(AbstractHistogram targetHistogram, long expectedIntervalBetweenValueSamples)
Copy this histogram, corrected for coordinated omission, into the target histogram, overwriting it's contents.static SynchronizedHistogram
decodeFromByteBuffer(java.nio.ByteBuffer buffer, long minBarForHighestTrackableValue)
Construct a new histogram by decoding it from a ByteBuffer.static SynchronizedHistogram
decodeFromCompressedByteBuffer(java.nio.ByteBuffer buffer, long minBarForHighestTrackableValue)
Construct a new histogram by decoding it from a compressed form in a ByteBuffer.int
encodeIntoByteBuffer(java.nio.ByteBuffer buffer)
Encode this histogram into a ByteBufferint
encodeIntoCompressedByteBuffer(java.nio.ByteBuffer targetBuffer)
Encode this histogram in compressed form into a byte arrayint
encodeIntoCompressedByteBuffer(java.nio.ByteBuffer targetBuffer, int compressionLevel)
Encode this histogram in compressed form into a byte arrayboolean
equals(java.lang.Object other)
Determine if this histogram is equivalent to another.long
getCountAtValue(long value)
Get the count of recorded values at a specific value (to within the histogram resolution at the value level).long
getCountBetweenValues(long lowValue, long highValue)
Get the count of recorded values within a range of value levels (inclusive to within the histogram's resolution).long
getEndTimeStamp()
get the end time stamp [optionally] stored with this histogramint
getEstimatedFootprintInBytes()
Provide a (conservatively high) estimate of the Histogram's total footprint in byteslong
getHighestTrackableValue()
get the configured highestTrackableValuelong
getLowestDiscernibleValue()
get the configured lowestDiscernibleValuelong
getMaxValue()
Get the highest recorded value level in the histogram.double
getMaxValueAsDouble()
Get the highest recorded value level in the histogram as a doubledouble
getMean()
Get the computed mean value of all recorded values in the histogramlong
getMinNonZeroValue()
Get the lowest recorded non-zero value level in the histogram.long
getMinValue()
Get the lowest recorded value level in the histogram.int
getNeededByteBufferCapacity()
Get the capacity needed to encode this histogram into a ByteBufferint
getNumberOfSignificantValueDigits()
get the configured numberOfSignificantValueDigitsdouble
getPercentileAtOrBelowValue(long value)
Get the percentile at a given value.long
getStartTimeStamp()
get the start time stamp [optionally] stored with this histogramdouble
getStdDeviation()
Get the computed standard deviation of all recorded values in the histogramlong
getTotalCount()
Get the total count of all recorded values in the histogramlong
getValueAtPercentile(double percentile)
Get the value at a given percentile.int
hashCode()
long
highestEquivalentValue(long value)
Get the highest value that is equivalent to the given value within the histogram's resolution.boolean
isAutoResize()
Indicate whether or not the histogram is set to auto-resize and auto-adjust it's highestTrackableValueAbstractHistogram.LinearBucketValues
linearBucketValues(long valueUnitsPerBucket)
Provide a means of iterating through histogram values using linear steps.AbstractHistogram.LogarithmicBucketValues
logarithmicBucketValues(long valueUnitsInFirstBucket, double logBase)
Provide a means of iterating through histogram values at logarithmically increasing levels.long
lowestEquivalentValue(long value)
Get the lowest value that is equivalent to the given value within the histogram's resolution.long
medianEquivalentValue(long value)
Get a value that lies in the middle (rounded up) of the range of values equivalent the given value.long
nextNonEquivalentValue(long value)
Get the next value that is not equivalent to the given value within the histogram's resolution.void
outputPercentileDistribution(java.io.PrintStream printStream, int percentileTicksPerHalfDistance, java.lang.Double outputValueUnitScalingRatio)
Produce textual representation of the value distribution of histogram data by percentile.void
outputPercentileDistribution(java.io.PrintStream printStream, int percentileTicksPerHalfDistance, java.lang.Double outputValueUnitScalingRatio, boolean useCsvFormat)
Produce textual representation of the value distribution of histogram data by percentile.void
outputPercentileDistribution(java.io.PrintStream printStream, java.lang.Double outputValueUnitScalingRatio)
Produce textual representation of the value distribution of histogram data by percentile.AbstractHistogram.Percentiles
percentiles(int percentileTicksPerHalfDistance)
Provide a means of iterating through histogram values according to percentile levels.private void
readObject(java.io.ObjectInputStream o)
AbstractHistogram.RecordedValues
recordedValues()
Provide a means of iterating through all recorded histogram values using the finest granularity steps supported by the underlying representation.void
recordValue(long value)
Record a value in the histogramvoid
recordValue(long value, long expectedIntervalBetweenValueSamples)
Deprecated.void
recordValueWithCount(long value, long count)
Record a value in the histogram (adding to the value's current count)void
recordValueWithExpectedInterval(long value, long expectedIntervalBetweenValueSamples)
Record a value in the histogram.void
reset()
Reset the contents and stats of this histogramvoid
setAutoResize(boolean autoResize)
Control whether or not the histogram can auto-resize and auto-adjust it's highestTrackableValuevoid
setEndTimeStamp(long timeStampMsec)
Set the end time stamp value associated with this histogram to a given value.void
setStartTimeStamp(long timeStampMsec)
Set the start time stamp value associated with this histogram to a given value.void
shiftValuesLeft(int numberOfBinaryOrdersOfMagnitude)
Shift recorded values to the left (the equivalent of a << shift operation on all recorded values).void
shiftValuesRight(int numberOfBinaryOrdersOfMagnitude)
Shift recorded values to the right (the equivalent of a >> shift operation on all recorded values).long
sizeOfEquivalentValueRange(long value)
Get the size (in value units) of the range of values that are equivalent to the given value within the histogram's resolution.void
subtract(AbstractHistogram otherHistogram)
Subtract the contents of another histogram from this one.boolean
valuesAreEquivalent(long value1, long value2)
Determine if two values are equivalent with the histogram's resolution.-
Methods inherited from class org.HdrHistogram.Histogram
_getEstimatedFootprintInBytes, addToCountAtIndex, addToTotalCount, clearCounts, fillCountsArrayFromBuffer, getCountAtIndex, getCountAtNormalizedIndex, getNormalizingIndexOffset, incrementCountAtIndex, incrementTotalCount, resize, setCountAtIndex, setCountAtNormalizedIndex, setIntegerToDoubleValueConversionRatio, setNormalizingIndexOffset, setTotalCount, shiftNormalizingIndexByOffset
-
Methods inherited from class org.HdrHistogram.AbstractHistogram
countsArrayIndex, decodeFromByteBuffer, decodeFromCompressedByteBuffer, determineArrayLengthNeeded, establishInternalTackingValues, establishInternalTackingValues, establishSize, fillBufferFromCountsArray, getBucketIndex, getBucketsNeededToCoverValue, getLengthForNumberOfBuckets, getNeededByteBufferCapacity, getNeededPayloadByteBufferCapacity, getNeededV0PayloadByteBufferCapacity, getSubBucketIndex, getTag, nonConcurrentNormalizingIndexShift, normalizeIndex, numberOfSubbuckets, recordConvertedDoubleValue, recordConvertedDoubleValueWithCount, setTag, shiftValuesLeft, shiftValuesRight, supportsAutoResize, updateMinAndMax, valueFromIndex
-
Methods inherited from class org.HdrHistogram.AbstractHistogramBase
getDoubleToIntegerValueConversionRatio, getIntegerToDoubleValueConversionRatio, nonConcurrentSetIntegerToDoubleValueConversionRatio
-
-
-
-
Constructor Detail
-
SynchronizedHistogram
public SynchronizedHistogram(int numberOfSignificantValueDigits)
Construct an auto-resizing SynchronizedHistogram 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
- 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.
-
SynchronizedHistogram
public SynchronizedHistogram(long highestTrackableValue, int numberOfSignificantValueDigits)
Construct a SynchronizedHistogram 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
- The highest value to be tracked by the histogram. Must be a positive integer that is >= 2.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.
-
SynchronizedHistogram
public SynchronizedHistogram(long lowestDiscernibleValue, long highestTrackableValue, int numberOfSignificantValueDigits)
Construct a SynchronizedHistogram 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
- 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
- The highest value to be tracked by the histogram. Must be a positive integer that is >= (2 * lowestDiscernibleValue).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.
-
SynchronizedHistogram
public SynchronizedHistogram(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
- The source histogram to duplicate
-
-
Method Detail
-
decodeFromByteBuffer
public static SynchronizedHistogram decodeFromByteBuffer(java.nio.ByteBuffer buffer, long minBarForHighestTrackableValue)
Construct a new histogram by decoding it from a ByteBuffer.- Parameters:
buffer
- The buffer to decode fromminBarForHighestTrackableValue
- Force highestTrackableValue to be set at least this high- Returns:
- The newly constructed histogram
-
decodeFromCompressedByteBuffer
public static SynchronizedHistogram decodeFromCompressedByteBuffer(java.nio.ByteBuffer buffer, long minBarForHighestTrackableValue) throws java.util.zip.DataFormatException
Construct a new histogram by decoding it from a compressed form in a ByteBuffer.- Parameters:
buffer
- The buffer to decode fromminBarForHighestTrackableValue
- Force highestTrackableValue to be set at least this high- Returns:
- The newly constructed histogram
- Throws:
java.util.zip.DataFormatException
- on error parsing/decompressing the buffer
-
getTotalCount
public long getTotalCount()
Description copied from class:AbstractHistogram
Get the total count of all recorded values in the histogram- Overrides:
getTotalCount
in classHistogram
- Returns:
- the total count of all recorded values in the histogram
-
isAutoResize
public boolean isAutoResize()
Description copied from class:AbstractHistogram
Indicate whether or not the histogram is set to auto-resize and auto-adjust it's highestTrackableValue- Overrides:
isAutoResize
in classAbstractHistogram
- Returns:
- autoResize setting
-
setAutoResize
public void setAutoResize(boolean autoResize)
Description copied from class:AbstractHistogram
Control whether or not the histogram can auto-resize and auto-adjust it's highestTrackableValue- Overrides:
setAutoResize
in classAbstractHistogram
- Parameters:
autoResize
- autoResize setting
-
recordValue
public void recordValue(long value) throws java.lang.ArrayIndexOutOfBoundsException
Description copied from class:AbstractHistogram
Record a value in the histogram- Specified by:
recordValue
in interfaceValueRecorder
- Overrides:
recordValue
in classAbstractHistogram
- Parameters:
value
- The value to be recorded- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if value is exceeds highestTrackableValue
-
recordValueWithCount
public void recordValueWithCount(long value, long count) throws java.lang.ArrayIndexOutOfBoundsException
Description copied from class:AbstractHistogram
Record a value in the histogram (adding to the value's current count)- Specified by:
recordValueWithCount
in interfaceValueRecorder
- Overrides:
recordValueWithCount
in classAbstractHistogram
- Parameters:
value
- The value to be recordedcount
- The number of occurrences of this value to record- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if value is exceeds highestTrackableValue
-
recordValueWithExpectedInterval
public void recordValueWithExpectedInterval(long value, long expectedIntervalBetweenValueSamples) throws java.lang.ArrayIndexOutOfBoundsException
Description copied from class:AbstractHistogram
Record a value in the histogram.To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, Histogram will auto-generate an additional series of decreasingly-smaller (down to the expectedIntervalBetweenValueSamples) value records.
Note: This is a at-recording correction method, as opposed to the post-recording correction method provided by
AbstractHistogram.copyCorrectedForCoordinatedOmission(long)
. 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.See notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.
- Specified by:
recordValueWithExpectedInterval
in interfaceValueRecorder
- Overrides:
recordValueWithExpectedInterval
in classAbstractHistogram
- Parameters:
value
- The value to recordexpectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if value is exceeds highestTrackableValue
-
recordValue
public void recordValue(long value, long expectedIntervalBetweenValueSamples) throws java.lang.ArrayIndexOutOfBoundsException
Deprecated.- Overrides:
recordValue
in classAbstractHistogram
- Parameters:
value
- The value to recordexpectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if value is exceeds highestTrackableValue
-
reset
public void reset()
Description copied from class:AbstractHistogram
Reset the contents and stats of this histogram- Specified by:
reset
in interfaceValueRecorder
- Overrides:
reset
in classAbstractHistogram
-
copy
public SynchronizedHistogram copy()
Description copied from class:AbstractHistogram
Create a copy of this histogram, complete with data and everything.
-
copyCorrectedForCoordinatedOmission
public SynchronizedHistogram copyCorrectedForCoordinatedOmission(long expectedIntervalBetweenValueSamples)
Description copied from class:AbstractHistogram
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. bySee notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.
- Overrides:
copyCorrectedForCoordinatedOmission
in classHistogram
- Parameters:
expectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples- Returns:
- a copy of this histogram, corrected for coordinated omission.
-
copyInto
public void copyInto(AbstractHistogram targetHistogram)
Description copied from class:AbstractHistogram
Copy this histogram into the target histogram, overwriting it's contents.- Overrides:
copyInto
in classAbstractHistogram
- Parameters:
targetHistogram
- the histogram to copy into
-
copyIntoCorrectedForCoordinatedOmission
public void copyIntoCorrectedForCoordinatedOmission(AbstractHistogram targetHistogram, long expectedIntervalBetweenValueSamples)
Description copied from class:AbstractHistogram
Copy this histogram, corrected for coordinated omission, into the target histogram, overwriting it's contents. (seeAbstractHistogram.copyCorrectedForCoordinatedOmission(long)
for more detailed explanation about how correction is applied)- Overrides:
copyIntoCorrectedForCoordinatedOmission
in classAbstractHistogram
- Parameters:
targetHistogram
- the histogram to copy intoexpectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
-
add
public void add(AbstractHistogram otherHistogram)
Description copied from class:AbstractHistogram
Add the contents of another histogram to this one.As part of adding the contents, the start/end timestamp range of this histogram will be extended to include the start/end timestamp range of the other histogram.
- Overrides:
add
in classAbstractHistogram
- Parameters:
otherHistogram
- The other histogram.
-
subtract
public void subtract(AbstractHistogram otherHistogram) throws java.lang.ArrayIndexOutOfBoundsException, java.lang.IllegalArgumentException
Description copied from class:AbstractHistogram
Subtract the contents of another histogram from this one.The start/end timestamps of this histogram will remain unchanged.
- Overrides:
subtract
in classAbstractHistogram
- Parameters:
otherHistogram
- The other histogram.- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if values in otherHistogram's are higher than highestTrackableValue.java.lang.IllegalArgumentException
-
addWhileCorrectingForCoordinatedOmission
public void addWhileCorrectingForCoordinatedOmission(AbstractHistogram fromHistogram, long expectedIntervalBetweenValueSamples)
Description copied from class:AbstractHistogram
Add the contents of another histogram to this one, while correcting the incoming data 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 values added 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-recording 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. bySee notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.
- Overrides:
addWhileCorrectingForCoordinatedOmission
in classAbstractHistogram
- Parameters:
fromHistogram
- The other histogram. highestTrackableValue and largestValueWithSingleUnitResolution must match.expectedIntervalBetweenValueSamples
- If expectedIntervalBetweenValueSamples is larger than 0, add auto-generated value records as appropriate if value is larger than expectedIntervalBetweenValueSamples
-
shiftValuesLeft
public void shiftValuesLeft(int numberOfBinaryOrdersOfMagnitude)
Description copied from class:AbstractHistogram
Shift recorded values to the left (the equivalent of a << shift operation on all recorded values). The configured integer value range limits and value precision setting will remain unchanged. AnArrayIndexOutOfBoundsException
will be thrown if any recorded values may be lost as a result of the attempted operation, reflecting an "overflow" conditions. Expect such an overflow exception if the operation would cause the current maxValue to be scaled to a value that is outside of the covered value range.- Overrides:
shiftValuesLeft
in classAbstractHistogram
- Parameters:
numberOfBinaryOrdersOfMagnitude
- The number of binary orders of magnitude to shift by
-
shiftValuesRight
public void shiftValuesRight(int numberOfBinaryOrdersOfMagnitude)
Description copied from class:AbstractHistogram
Shift recorded values to the right (the equivalent of a >> shift operation on all recorded values). The configured integer value range limits and value precision setting will remain unchanged.Shift right operations that do not underflow are reversible with a shift left operation with no loss of information. An
ArrayIndexOutOfBoundsException
reflecting an "underflow" conditions will be thrown if any recorded values may lose representation accuracy as a result of the attempted shift operation.For a shift of a single order of magnitude, expect such an underflow exception if any recorded non-zero values up to [numberOfSignificantValueDigits (rounded up to nearest power of 2) multiplied by (2 ^ numberOfBinaryOrdersOfMagnitude) currently exist in the histogram.
- Overrides:
shiftValuesRight
in classAbstractHistogram
- Parameters:
numberOfBinaryOrdersOfMagnitude
- The number of binary orders of magnitude to shift by
-
equals
public boolean equals(java.lang.Object other)
Description copied from class:AbstractHistogram
Determine if this histogram is equivalent to another.- Overrides:
equals
in classAbstractHistogram
- Parameters:
other
- the other histogram to compare to- Returns:
- True if this histogram are equivalent with the other.
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classAbstractHistogram
-
getLowestDiscernibleValue
public long getLowestDiscernibleValue()
Description copied from class:AbstractHistogram
get the configured lowestDiscernibleValue- Overrides:
getLowestDiscernibleValue
in classAbstractHistogram
- Returns:
- lowestDiscernibleValue
-
getHighestTrackableValue
public long getHighestTrackableValue()
Description copied from class:AbstractHistogram
get the configured highestTrackableValue- Overrides:
getHighestTrackableValue
in classAbstractHistogram
- Returns:
- highestTrackableValue
-
getNumberOfSignificantValueDigits
public int getNumberOfSignificantValueDigits()
Description copied from class:AbstractHistogram
get the configured numberOfSignificantValueDigits- Overrides:
getNumberOfSignificantValueDigits
in classAbstractHistogram
- Returns:
- numberOfSignificantValueDigits
-
sizeOfEquivalentValueRange
public long sizeOfEquivalentValueRange(long value)
Description copied from class:AbstractHistogram
Get the size (in value units) of the range of values that are 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.- Overrides:
sizeOfEquivalentValueRange
in classAbstractHistogram
- Parameters:
value
- The given value- Returns:
- The size of the range of values equivalent to the given value.
-
lowestEquivalentValue
public long lowestEquivalentValue(long value)
Description copied from class:AbstractHistogram
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.- Overrides:
lowestEquivalentValue
in classAbstractHistogram
- Parameters:
value
- The given value- Returns:
- The lowest value that is equivalent to the given value within the histogram's resolution.
-
highestEquivalentValue
public long highestEquivalentValue(long value)
Description copied from class:AbstractHistogram
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.- Overrides:
highestEquivalentValue
in classAbstractHistogram
- Parameters:
value
- The given value- Returns:
- The highest value that is equivalent to the given value within the histogram's resolution.
-
medianEquivalentValue
public long medianEquivalentValue(long value)
Description copied from class:AbstractHistogram
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.- Overrides:
medianEquivalentValue
in classAbstractHistogram
- Parameters:
value
- The given value- Returns:
- The value lies in the middle (rounded up) of the range of values equivalent the given value.
-
nextNonEquivalentValue
public long nextNonEquivalentValue(long value)
Description copied from class:AbstractHistogram
Get the next value that is not 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.- Overrides:
nextNonEquivalentValue
in classAbstractHistogram
- Parameters:
value
- The given value- Returns:
- The next value that is not equivalent to the given value within the histogram's resolution.
-
valuesAreEquivalent
public boolean valuesAreEquivalent(long value1, long value2)
Description copied from class:AbstractHistogram
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.- Overrides:
valuesAreEquivalent
in classAbstractHistogram
- Parameters:
value1
- first value to comparevalue2
- second value to compare- Returns:
- True if values are equivalent with the histogram's resolution.
-
getEstimatedFootprintInBytes
public int getEstimatedFootprintInBytes()
Description copied from class:AbstractHistogram
Provide a (conservatively high) estimate of the Histogram's total footprint in bytes- Overrides:
getEstimatedFootprintInBytes
in classAbstractHistogram
- Returns:
- a (conservatively high) estimate of the Histogram's total footprint in bytes
-
getStartTimeStamp
public long getStartTimeStamp()
Description copied from class:AbstractHistogram
get the start time stamp [optionally] stored with this histogram- Overrides:
getStartTimeStamp
in classAbstractHistogram
- Returns:
- the start time stamp [optionally] stored with this histogram
-
setStartTimeStamp
public void setStartTimeStamp(long timeStampMsec)
Description copied from class:AbstractHistogram
Set the start time stamp value associated with this histogram to a given value.- Overrides:
setStartTimeStamp
in classAbstractHistogram
- Parameters:
timeStampMsec
- the value to set the time stamp to, [by convention] in msec since the epoch.
-
getEndTimeStamp
public long getEndTimeStamp()
Description copied from class:AbstractHistogram
get the end time stamp [optionally] stored with this histogram- Overrides:
getEndTimeStamp
in classAbstractHistogram
- Returns:
- the end time stamp [optionally] stored with this histogram
-
setEndTimeStamp
public void setEndTimeStamp(long timeStampMsec)
Description copied from class:AbstractHistogram
Set the end time stamp value associated with this histogram to a given value.- Overrides:
setEndTimeStamp
in classAbstractHistogram
- Parameters:
timeStampMsec
- the value to set the time stamp to, [by convention] in msec since the epoch.
-
getMinValue
public long getMinValue()
Description copied from class:AbstractHistogram
Get the lowest recorded value level in the histogram. If the histogram has no recorded values, the value returned is undefined.- Overrides:
getMinValue
in classAbstractHistogram
- Returns:
- the Min value recorded in the histogram
-
getMaxValue
public long getMaxValue()
Description copied from class:AbstractHistogram
Get the highest recorded value level in the histogram. If the histogram has no recorded values, the value returned is undefined.- Overrides:
getMaxValue
in classAbstractHistogram
- Returns:
- the Max value recorded in the histogram
-
getMinNonZeroValue
public long getMinNonZeroValue()
Description copied from class:AbstractHistogram
Get the lowest recorded non-zero value level in the histogram. If the histogram has no recorded values, the value returned is undefined.- Overrides:
getMinNonZeroValue
in classAbstractHistogram
- Returns:
- the lowest recorded non-zero value level in the histogram
-
getMaxValueAsDouble
public double getMaxValueAsDouble()
Description copied from class:AbstractHistogram
Get the highest recorded value level in the histogram as a double- Overrides:
getMaxValueAsDouble
in classAbstractHistogram
- Returns:
- the Max value recorded in the histogram
-
getMean
public double getMean()
Description copied from class:AbstractHistogram
Get the computed mean value of all recorded values in the histogram- Overrides:
getMean
in classAbstractHistogram
- Returns:
- the mean value (in value units) of the histogram data
-
getStdDeviation
public double getStdDeviation()
Description copied from class:AbstractHistogram
Get the computed standard deviation of all recorded values in the histogram- Overrides:
getStdDeviation
in classAbstractHistogram
- Returns:
- the standard deviation (in value units) of the histogram data
-
getValueAtPercentile
public long getValueAtPercentile(double percentile)
Description copied from class:AbstractHistogram
Get the value at a given percentile. Returns the largest value that (100% - percentile) [+/- 1 ulp] of the overall recorded value entries in the histogram are either larger than or equivalent to. Returns 0 if no recorded values exist.Note that two values are "equivalent" in this statement if
AbstractHistogram.valuesAreEquivalent(long, long)
would return true.- Overrides:
getValueAtPercentile
in classAbstractHistogram
- Parameters:
percentile
- The percentile for which to return the associated value- Returns:
- The largest value that (100% - percentile) [+/- 1 ulp] of the overall recorded value entries in the histogram are either larger than or equivalent to. Returns 0 if no recorded values exist.
-
getPercentileAtOrBelowValue
public double getPercentileAtOrBelowValue(long value)
Description copied from class:AbstractHistogram
Get the percentile at a given value. The percentile returned is the percentile of values recorded in the histogram that are smaller than or equivalent to the given value.Note that two values are "equivalent" in this statement if
AbstractHistogram.valuesAreEquivalent(long, long)
would return true.- Overrides:
getPercentileAtOrBelowValue
in classAbstractHistogram
- Parameters:
value
- The value for which to return the associated percentile- Returns:
- The percentile of values recorded in the histogram that are smaller than or equivalent to the given value.
-
getCountBetweenValues
public long getCountBetweenValues(long lowValue, long highValue) throws java.lang.ArrayIndexOutOfBoundsException
Description copied from class:AbstractHistogram
Get the count of recorded values within a range of value levels (inclusive to within the histogram's resolution).- Overrides:
getCountBetweenValues
in classAbstractHistogram
- Parameters:
lowValue
- The lower value bound on the range for which to provide the recorded count. Will be rounded down withlowestEquivalentValue
.highValue
- The higher value bound on the range for which to provide the recorded count. Will be rounded up withhighestEquivalentValue
.- Returns:
- the total count of values recorded in the histogram within the value range that is >= lowestEquivalentValue(lowValue) and <= highestEquivalentValue(highValue)
- Throws:
java.lang.ArrayIndexOutOfBoundsException
-
getCountAtValue
public long getCountAtValue(long value) throws java.lang.ArrayIndexOutOfBoundsException
Description copied from class:AbstractHistogram
Get the count of recorded values at a specific value (to within the histogram resolution at the value level).- Overrides:
getCountAtValue
in classAbstractHistogram
- Parameters:
value
- The value for which to provide the recorded count- Returns:
- The total count of values recorded in the histogram within the value range that is >= lowestEquivalentValue(value) and <= highestEquivalentValue(value)
- Throws:
java.lang.ArrayIndexOutOfBoundsException
-
percentiles
public AbstractHistogram.Percentiles percentiles(int percentileTicksPerHalfDistance)
Description copied from class:AbstractHistogram
Provide a means of iterating through histogram values according to percentile levels. The iteration is performed in steps that start at 0% and reduce their distance to 100% according to the percentileTicksPerHalfDistance parameter, ultimately reaching 100% when all recorded histogram values are exhausted.- Overrides:
percentiles
in classAbstractHistogram
- Parameters:
percentileTicksPerHalfDistance
- The number of iteration steps per half-distance to 100%.- Returns:
- An
Iterable
<HistogramIterationValue
> through the histogram using aPercentileIterator
-
linearBucketValues
public AbstractHistogram.LinearBucketValues linearBucketValues(long valueUnitsPerBucket)
Description copied from class:AbstractHistogram
Provide a means of iterating through histogram values using linear steps. The iteration is performed in steps of valueUnitsPerBucket in size, terminating when all recorded histogram values are exhausted.- Overrides:
linearBucketValues
in classAbstractHistogram
- Parameters:
valueUnitsPerBucket
- The size (in value units) of the linear buckets to use- Returns:
- An
Iterable
<HistogramIterationValue
> through the histogram using aLinearIterator
-
logarithmicBucketValues
public AbstractHistogram.LogarithmicBucketValues logarithmicBucketValues(long valueUnitsInFirstBucket, double logBase)
Description copied from class:AbstractHistogram
Provide a means of iterating through histogram values at logarithmically increasing levels. The iteration is performed in steps that start at valueUnitsInFirstBucket and increase exponentially according to logBase, terminating when all recorded histogram values are exhausted.- Overrides:
logarithmicBucketValues
in classAbstractHistogram
- Parameters:
valueUnitsInFirstBucket
- The size (in value units) of the first bucket in the iterationlogBase
- The multiplier by which bucket sizes will grow in each iteration step- Returns:
- An
Iterable
<HistogramIterationValue
> through the histogram using aLogarithmicIterator
-
recordedValues
public AbstractHistogram.RecordedValues recordedValues()
Description copied from class:AbstractHistogram
Provide a means of iterating through all recorded histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all non-zero recorded value counts, and terminates when all recorded histogram values are exhausted.- Overrides:
recordedValues
in classAbstractHistogram
- Returns:
- An
Iterable
<HistogramIterationValue
> through the histogram using aRecordedValuesIterator
-
allValues
public AbstractHistogram.AllValues allValues()
Description copied from class:AbstractHistogram
Provide a means of iterating through all histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all possible unit value levels, regardless of whether or not there were recorded values for that value level, and terminates when all recorded histogram values are exhausted.- Overrides:
allValues
in classAbstractHistogram
- Returns:
- An
Iterable
<HistogramIterationValue
> through the histogram using aAllValuesIterator
-
outputPercentileDistribution
public void outputPercentileDistribution(java.io.PrintStream printStream, java.lang.Double outputValueUnitScalingRatio)
Description copied from class:AbstractHistogram
Produce textual representation of the value distribution of histogram data by percentile. The distribution is output with exponentially increasing resolution, with each exponentially decreasing half-distance containing five (5) percentile reporting tick points.- Overrides:
outputPercentileDistribution
in classAbstractHistogram
- Parameters:
printStream
- Stream into which the distribution will be outputoutputValueUnitScalingRatio
- The scaling factor by which to divide histogram recorded values units in output
-
outputPercentileDistribution
public void outputPercentileDistribution(java.io.PrintStream printStream, int percentileTicksPerHalfDistance, java.lang.Double outputValueUnitScalingRatio)
Description copied from class:AbstractHistogram
Produce textual representation of the value distribution of histogram data by percentile. The distribution is output with exponentially increasing resolution, with each exponentially decreasing half-distance containing dumpTicksPerHalf percentile reporting tick points.- Overrides:
outputPercentileDistribution
in classAbstractHistogram
- Parameters:
printStream
- Stream into which the distribution will be outputpercentileTicksPerHalfDistance
- The number of reporting points per exponentially decreasing half-distanceoutputValueUnitScalingRatio
- The scaling factor by which to divide histogram recorded values units in output
-
outputPercentileDistribution
public void outputPercentileDistribution(java.io.PrintStream printStream, int percentileTicksPerHalfDistance, java.lang.Double outputValueUnitScalingRatio, boolean useCsvFormat)
Description copied from class:AbstractHistogram
Produce textual representation of the value distribution of histogram data by percentile. The distribution is output with exponentially increasing resolution, with each exponentially decreasing half-distance containing dumpTicksPerHalf percentile reporting tick points.- Overrides:
outputPercentileDistribution
in classAbstractHistogram
- Parameters:
printStream
- Stream into which the distribution will be outputpercentileTicksPerHalfDistance
- The number of reporting points per exponentially decreasing half-distanceoutputValueUnitScalingRatio
- The scaling factor by which to divide histogram recorded values units in outputuseCsvFormat
- Output in CSV format if true. Otherwise use plain text form.
-
getNeededByteBufferCapacity
public int getNeededByteBufferCapacity()
Description copied from class:AbstractHistogram
Get the capacity needed to encode this histogram into a ByteBuffer- Overrides:
getNeededByteBufferCapacity
in classAbstractHistogram
- Returns:
- the capacity needed to encode this histogram into a ByteBuffer
-
encodeIntoByteBuffer
public int encodeIntoByteBuffer(java.nio.ByteBuffer buffer)
Description copied from class:AbstractHistogram
Encode this histogram into a ByteBuffer- Overrides:
encodeIntoByteBuffer
in classAbstractHistogram
- Parameters:
buffer
- The buffer to encode into- Returns:
- The number of bytes written to the buffer
-
encodeIntoCompressedByteBuffer
public int encodeIntoCompressedByteBuffer(java.nio.ByteBuffer targetBuffer, int compressionLevel)
Description copied from class:AbstractHistogram
Encode this histogram in compressed form into a byte array- Overrides:
encodeIntoCompressedByteBuffer
in classAbstractHistogram
- Parameters:
targetBuffer
- The buffer to encode intocompressionLevel
- Compression level (for java.util.zip.Deflater).- Returns:
- The number of bytes written to the buffer
-
encodeIntoCompressedByteBuffer
public int encodeIntoCompressedByteBuffer(java.nio.ByteBuffer targetBuffer)
Description copied from class:AbstractHistogram
Encode this histogram in compressed form into a byte array- Overrides:
encodeIntoCompressedByteBuffer
in classAbstractHistogram
- Parameters:
targetBuffer
- The buffer to encode into- Returns:
- The number of bytes written to the array
-
readObject
private void readObject(java.io.ObjectInputStream o) throws java.io.IOException, java.lang.ClassNotFoundException
- Throws:
java.io.IOException
java.lang.ClassNotFoundException
-
-