org.HdrHistogram
Class SynchronizedHistogram

java.lang.Object
  org.HdrHistogram.EncodableHistogram
      org.HdrHistogram.AbstractHistogram
          org.HdrHistogram.Histogram
              org.HdrHistogram.SynchronizedHistogram

All Implemented Interfaces:

Serializable

public class SynchronizedHistogram
extends Histogram

An integer values High Dynamic Range (HDR) Histogram that is synchronized as a whole

A SynchronizedHistogram is a variant of Histogram that is synchronized as a whole, such that queries, copying, and addition operations are atomic with relation to modification on the SynchronizedHistogram, and such that external accessors (e.g. iterations on the histogram data) that synchronize on the SynchronizedHistogram 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 or SingleWriterRecorder which were intended for concurrent operations.

See package description for org.HdrHistogram and Histogram 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

Constructor Summary

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)

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.

Method Summary

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(ByteBuffer buffer, long minBarForHighestTrackableValue) Construct a new histogram by decoding it from a ByteBuffer.
static SynchronizedHistogram	decodeFromCompressedByteBuffer(ByteBuffer buffer, long minBarForHighestTrackableValue) Construct a new histogram by decoding it from a compressed form in a ByteBuffer.
int	encodeIntoByteBuffer(ByteBuffer buffer) Encode this histogram into a ByteBuffer
int	encodeIntoCompressedByteBuffer(ByteBuffer targetBuffer) Encode this histogram in compressed form into a byte array
int	encodeIntoCompressedByteBuffer(ByteBuffer targetBuffer, int compressionLevel) Encode this histogram in compressed form into a byte array
boolean	equals(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 histogram
int	getEstimatedFootprintInBytes() Provide a (conservatively high) estimate of the Histogram's total footprint in bytes
long	getHighestTrackableValue() get the configured highestTrackableValue
long	getLowestDiscernibleValue() get the configured lowestDiscernibleValue
long	getMaxValue() Get the highest recorded value level in the histogram.
double	getMaxValueAsDouble() Get the highest recorded value level in the histogram as a double
double	getMean() Get the computed mean value of all recorded values in the histogram
long	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 ByteBuffer
int	getNumberOfSignificantValueDigits() get the configured numberOfSignificantValueDigits
double	getPercentileAtOrBelowValue(long value) Get the percentile at a given value.
long	getStartTimeStamp() get the start time stamp [optionally] stored with this histogram
double	getStdDeviation() Get the computed standard deviation of all recorded values in the histogram
long	getTotalCount() Get the total count of all recorded values in the histogram
long	getValueAtPercentile(double percentile) Get the value at a given percentile.
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 highestTrackableValue
AbstractHistogram.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(PrintStream printStream, Double outputValueUnitScalingRatio) Produce textual representation of the value distribution of histogram data by percentile.
void	outputPercentileDistribution(PrintStream printStream, int percentileTicksPerHalfDistance, Double outputValueUnitScalingRatio) Produce textual representation of the value distribution of histogram data by percentile.
void	outputPercentileDistribution(PrintStream printStream, int percentileTicksPerHalfDistance, Double outputValueUnitScalingRatio, boolean useCsvFormat) 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.
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 histogram
void	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 histogram
void	setAutoResize(boolean autoResize) Control whether or not the histogram can auto-resize and auto-adjust it's highestTrackableValue
void	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 java.lang.Object

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

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(ByteBuffer buffer,
                                                         long minBarForHighestTrackableValue)

Construct a new histogram by decoding it from a ByteBuffer.

Parameters:

buffer - The buffer to decode from

minBarForHighestTrackableValue - Force highestTrackableValue to be set at least this high

Returns:

The newly constructed histogram

decodeFromCompressedByteBuffer

public static SynchronizedHistogram decodeFromCompressedByteBuffer(ByteBuffer buffer,
                                                                   long minBarForHighestTrackableValue)
                                                            throws DataFormatException

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

Parameters:

buffer - The buffer to decode from

minBarForHighestTrackableValue - Force highestTrackableValue to be set at least this high

Returns:

The newly constructed histogram

Throws:

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 class Histogram

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 class AbstractHistogram

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 class AbstractHistogram

Parameters:

autoResize - autoResize setting

recordValue

public void recordValue(long value)
                 throws ArrayIndexOutOfBoundsException

Description copied from class: AbstractHistogram

Record a value in the histogram

Overrides:

recordValue in class AbstractHistogram

Parameters:

value - The value to be recorded

Throws:

ArrayIndexOutOfBoundsException - (may throw) if value is exceeds highestTrackableValue

recordValueWithCount

public void recordValueWithCount(long value,
                                 long count)
                          throws ArrayIndexOutOfBoundsException

Description copied from class: AbstractHistogram

Record a value in the histogram (adding to the value's current count)

Overrides:

recordValueWithCount in class AbstractHistogram

Parameters:

value - The value to be recorded

count - The number of occurrences of this value to record

Throws:

ArrayIndexOutOfBoundsException - (may throw) if value is exceeds highestTrackableValue

recordValueWithExpectedInterval

public void recordValueWithExpectedInterval(long value,
                                            long expectedIntervalBetweenValueSamples)
                                     throws 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.

Overrides:

recordValueWithExpectedInterval in class AbstractHistogram

Parameters:

value - The value to record

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

Throws:

ArrayIndexOutOfBoundsException - (may throw) if value is exceeds highestTrackableValue

recordValue

public void recordValue(long value,
                        long expectedIntervalBetweenValueSamples)
                 throws ArrayIndexOutOfBoundsException

Deprecated.

Overrides:

recordValue in class AbstractHistogram

Parameters:

value - The value to record

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

Throws:

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

Overrides:

reset in class AbstractHistogram

copy

public SynchronizedHistogram copy()

Description copied from class: AbstractHistogram

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

Overrides:

copy in class Histogram

Returns:

A distinct copy of this histogram.

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. by

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

Overrides:

copyCorrectedForCoordinatedOmission in class Histogram

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 class AbstractHistogram

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. (see AbstractHistogram.copyCorrectedForCoordinatedOmission(long) for more detailed explanation about how correction is applied)

Overrides:

copyIntoCorrectedForCoordinatedOmission in class AbstractHistogram

Parameters:

targetHistogram - the histogram to copy into

expectedIntervalBetweenValueSamples - 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 class AbstractHistogram

Parameters:

otherHistogram - The other histogram.

subtract

public void subtract(AbstractHistogram otherHistogram)
              throws ArrayIndexOutOfBoundsException,
                     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 class AbstractHistogram

Parameters:

otherHistogram - The other histogram.

Throws:

ArrayIndexOutOfBoundsException - (may throw) if values in otherHistogram's are higher than highestTrackableValue.

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. by

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

Overrides:

addWhileCorrectingForCoordinatedOmission in class AbstractHistogram

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. An ArrayIndexOutOfBoundsException 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 class AbstractHistogram

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 class AbstractHistogram

Parameters:

numberOfBinaryOrdersOfMagnitude - The number of binary orders of magnitude to shift by

equals

public boolean equals(Object other)

Description copied from class: AbstractHistogram

Determine if this histogram is equivalent to another.

Overrides:

equals in class AbstractHistogram

Parameters:

other - the other histogram to compare to

Returns:

True if this histogram are equivalent with the other.

getLowestDiscernibleValue

public long getLowestDiscernibleValue()

Description copied from class: AbstractHistogram

get the configured lowestDiscernibleValue

Overrides:

getLowestDiscernibleValue in class AbstractHistogram

Returns:

lowestDiscernibleValue

getHighestTrackableValue

public long getHighestTrackableValue()

Description copied from class: AbstractHistogram

get the configured highestTrackableValue

Overrides:

getHighestTrackableValue in class AbstractHistogram

Returns:

highestTrackableValue

getNumberOfSignificantValueDigits

public int getNumberOfSignificantValueDigits()

Description copied from class: AbstractHistogram

get the configured numberOfSignificantValueDigits

Overrides:

getNumberOfSignificantValueDigits in class AbstractHistogram

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 class AbstractHistogram

Parameters:

value - The given value

Returns:

The lowest value that is equivalent to the given value within the histogram's resolution.

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

Parameters:

value1 - first value to compare

value2 - 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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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 class AbstractHistogram

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. When the given percentile is > 0.0, the value returned is the value that the given percentage of the overall recorded value entries in the histogram are either smaller than or equivalent to. When the given percentile is 0.0, the value returned is the value that all value entries in the histogram are either larger than or equivalent to.

Note that two values are "equivalent" in this statement if AbstractHistogram.valuesAreEquivalent(long, long) would return true.

Overrides:

getValueAtPercentile in class AbstractHistogram

Parameters:

percentile - The percentile for which to return the associated value

Returns:

The value that the given percentage of the overall recorded value entries in the histogram are either smaller than or equivalent to. When the percentile is 0.0, returns the value that all value entries in the histogram are either larger than or equivalent to.

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 class AbstractHistogram

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 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 class AbstractHistogram

Parameters:

lowValue - The lower value bound on the range for which to provide the recorded count. Will be rounded down with lowestEquivalentValue.

highValue - The higher value bound on the range for which to provide the recorded count. Will be rounded up with highestEquivalentValue.

Returns:

the total count of values recorded in the histogram within the value range that is >= lowestEquivalentValue(lowValue) and <= highestEquivalentValue(highValue)

Throws:

ArrayIndexOutOfBoundsException

getCountAtValue

public long getCountAtValue(long value)
                     throws 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 class AbstractHistogram

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:

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 class AbstractHistogram

Parameters:

percentileTicksPerHalfDistance - The number of iteration steps per half-distance to 100%.

Returns:

An Iterable<HistogramIterationValue> through the histogram using a PercentileIterator

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 class AbstractHistogram

Parameters:

valueUnitsPerBucket - The size (in value units) of the linear buckets to use

Returns:

An Iterable<HistogramIterationValue> through the histogram using a LinearIterator

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 class AbstractHistogram

Parameters:

valueUnitsInFirstBucket - The size (in value units) of the first bucket in the iteration

logBase - The multiplier by which bucket sizes will grow in each iteration step

Returns:

An Iterable<HistogramIterationValue> through the histogram using a LogarithmicIterator

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 class AbstractHistogram

Returns:

An Iterable<HistogramIterationValue> through the histogram using a RecordedValuesIterator

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 class AbstractHistogram

Returns:

An Iterable<HistogramIterationValue> through the histogram using a AllValuesIterator

outputPercentileDistribution

public void outputPercentileDistribution(PrintStream printStream,
                                         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 class AbstractHistogram

Parameters:

printStream - Stream into which the distribution will be output

outputValueUnitScalingRatio - The scaling factor by which to divide histogram recorded values units in output

outputPercentileDistribution

public void outputPercentileDistribution(PrintStream printStream,
                                         int percentileTicksPerHalfDistance,
                                         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 class AbstractHistogram

Parameters:

printStream - Stream into which the distribution will be output

percentileTicksPerHalfDistance - The number of reporting points per exponentially decreasing half-distance

outputValueUnitScalingRatio - The scaling factor by which to divide histogram recorded values units in output

outputPercentileDistribution

public void outputPercentileDistribution(PrintStream printStream,
                                         int percentileTicksPerHalfDistance,
                                         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 class AbstractHistogram

Parameters:

printStream - Stream into which the distribution will be output

percentileTicksPerHalfDistance - The number of reporting points per exponentially decreasing half-distance

outputValueUnitScalingRatio - The scaling factor by which to divide histogram recorded values units in output

useCsvFormat - 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 class AbstractHistogram

Returns:

the capacity needed to encode this histogram into a ByteBuffer

encodeIntoByteBuffer

public int encodeIntoByteBuffer(ByteBuffer buffer)

Description copied from class: AbstractHistogram

Encode this histogram into a ByteBuffer

Overrides:

encodeIntoByteBuffer in class AbstractHistogram

Parameters:

buffer - The buffer to encode into

Returns:

The number of bytes written to the buffer

encodeIntoCompressedByteBuffer

public int encodeIntoCompressedByteBuffer(ByteBuffer targetBuffer,
                                          int compressionLevel)

Description copied from class: AbstractHistogram

Encode this histogram in compressed form into a byte array

Overrides:

encodeIntoCompressedByteBuffer in class AbstractHistogram

Parameters:

targetBuffer - The buffer to encode into

compressionLevel - Compression level (for java.util.zip.Deflater).

Returns:

The number of bytes written to the buffer

encodeIntoCompressedByteBuffer

public int encodeIntoCompressedByteBuffer(ByteBuffer targetBuffer)

Description copied from class: AbstractHistogram

Encode this histogram in compressed form into a byte array

Overrides:

encodeIntoCompressedByteBuffer in class AbstractHistogram

Parameters:

targetBuffer - The buffer to encode into

Returns:

The number of bytes written to the array