co.paralleluniverse.common.benchmark

Class StripedHistogram

java.lang.Object

co.paralleluniverse.common.benchmark.StripedHistogram

public class StripedHistogram
extends java.lang.Object

Constructor Summary

Constructors

Constructor and Description
StripedHistogram(long highestTrackableValue, int numberOfSignificantValueDigits) Construct a Histogram given the Highest value to be tracked and a number of significant decimal digits

Method Summary

Modifier and Type	Method and Description
void	combine()
long	getHighestTrackableValue() get the configured highestTrackableValue
org.HdrHistogram.AbstractHistogram	getHistogramDataCorrectedForCoordinatedOmission(long expectedIntervalBetweenValueSamples) Provide access to the histogram's data set, corrected for coordinated omission.
int	getNumberOfSignificantValueDigits() get the configured numberOfSignificantValueDigits
long	highestEquivalentValue(long value) Get the highest value that is equivalent to the given value within the histogram's resolution.
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	recordValue(long value) Record a value in the histogram
void	recordValue(long value, long expectedIntervalBetweenValueSamples) Deprecated. Record a value in the histogram. This deprecated method has identical behavior to recordValueWithExpectedInterval(). It was renamed to avoid ambiguity.
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
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.
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, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StripedHistogram

public StripedHistogram(long highestTrackableValue,
                        int numberOfSignificantValueDigits)

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

Parameters:

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

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

Method Detail

combine

public void combine()

recordValue

public void recordValue(long value)
                 throws java.lang.ArrayIndexOutOfBoundsException

Record a value in the histogram

Parameters:

value - The value to be recorded

Throws:

java.lang.ArrayIndexOutOfBoundsException

recordValueWithCount

public void recordValueWithCount(long value,
                                 long count)
                          throws java.lang.ArrayIndexOutOfBoundsException

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

Parameters:

value - The value to be recorded

count - The number of occurrences of this value to record

Throws:

java.lang.ArrayIndexOutOfBoundsException

recordValue

@Deprecated
public void recordValue(long value,
                                    long expectedIntervalBetweenValueSamples)
                             throws java.lang.ArrayIndexOutOfBoundsException

Deprecated. Record a value in the histogram. This deprecated method has identical behavior to recordValueWithExpectedInterval(). It was renamed to avoid ambiguity.

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:

java.lang.ArrayIndexOutOfBoundsException

recordValueWithExpectedInterval

public void recordValueWithExpectedInterval(long value,
                                            long expectedIntervalBetweenValueSamples)
                                     throws java.lang.ArrayIndexOutOfBoundsException

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

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:

java.lang.ArrayIndexOutOfBoundsException

reset

public void reset()

Reset the contents and stats of this histogram

getHistogramDataCorrectedForCoordinatedOmission

public org.HdrHistogram.AbstractHistogram getHistogramDataCorrectedForCoordinatedOmission(long expectedIntervalBetweenValueSamples)

Provide access to the histogram's data set, corrected for coordinated omission. 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.

Returns:

a HistogramData that can be used to query stats and iterate through the default (corrected) data set.

getNumberOfSignificantValueDigits

public int getNumberOfSignificantValueDigits()

get the configured numberOfSignificantValueDigits

Returns:

numberOfSignificantValueDigits

getHighestTrackableValue

public long getHighestTrackableValue()

get the configured highestTrackableValue

Returns:

highestTrackableValue

sizeOfEquivalentValueRange

public 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. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.

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)

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.

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)

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.

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)

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.

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)

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.

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)

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.

Parameters:

value1 - first value to compare

value2 - second value to compare

Returns:

True if values are equivalent with the histogram's resolution.