org.HdrHistogram
Class AbstractHistogram

java.lang.Object
  org.HdrHistogram.AbstractHistogram

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AtomicHistogram, Histogram, IntHistogram, ShortHistogram, SynchronizedHistogram

public abstract class AbstractHistogram
extends Object
implements Serializable

A High Dynamic Range (HDR) Histogram

AbstractHistogram supports the recording and analyzing sampled data value counts across a configurable integer value range with configurable value precision within the range. Value precision is expressed as the number of significant digits in the value recording, and provides control over value quantization behavior across the value range and the subsequent value resolution at any given level.

For example, a Histogram could be configured to track the counts of observed integer values between 0 and 3,600,000,000 while maintaining a value precision of 3 significant digits across that range. Value quantization within the range will thus be no larger than 1/1,000th (or 0.1%) of any value. This example Histogram could be used to track and analyze the counts of observed response times ranging between 1 microsecond and 1 hour in magnitude, while maintaining a value resolution of 1 microsecond up to 1 millisecond, a resolution of 1 millisecond (or better) up to one second, and a resolution of 1 second (or better) up to 1,000 seconds. At it's maximum tracked value (1 hour), it would still maintain a resolution of 3.6 seconds (or better).

See package description for org.HdrHistogram for details.

See Also:

Serialized Form

Nested Class Summary

class	AbstractHistogram.AllValues An Iterable<HistogramIterationValue> through the histogram using a AllValuesIterator
class	AbstractHistogram.LinearBucketValues An Iterable<HistogramIterationValue> through the histogram using a LinearIterator
class	AbstractHistogram.LogarithmicBucketValues An Iterable<HistogramIterationValue> through the histogram using a LogarithmicIterator
class	AbstractHistogram.Percentiles An Iterable<HistogramIterationValue> through the histogram using a PercentileIterator
class	AbstractHistogram.RecordedValues An Iterable<HistogramIterationValue> through the histogram using a RecordedValuesIterator

Constructor Summary

AbstractHistogram(long lowestTrackableValue, long highestTrackableValue, int numberOfSignificantValueDigits)
Construct a histogram given the Lowest and Highest values to be tracked and a number of significant decimal digits.

Method Summary

void	add(AbstractHistogram fromHistogram) 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.
abstract AbstractHistogram	copy() Create a copy of this histogram, complete with data and everything.
abstract AbstractHistogram	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.
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
long	getCountBetweenValues(long lowValue, long highValue) Get the count of recorded values within a range of value levels.
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
HistogramData	getHistogramData() Deprecated.
long	getLowestTrackableValue() get the configured lowestTrackableValue
long	getMaxValue() Get the highest recorded value level in the histogram
double	getMean() Get the computed mean value of all recorded values 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
abstract long	getTotalCount()
long	getValueAtPercentile(double percentile) Get the value at a given percentile
boolean	hasOverflowed() Determine if this histogram had any of it's value counts overflow.
long	highestEquivalentValue(long value) Get the highest value that is equivalent to the given value within the histogram's resolution.
AbstractHistogram.LinearBucketValues	linearBucketValues(int valueUnitsPerBucket) Provide a means of iterating through histogram values using linear steps.
AbstractHistogram.LogarithmicBucketValues	logarithmicBucketValues(int 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. 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	reestablishTotalCount() Reestablish the internal notion of totalCount by recalculating it from recorded values.
void	reset() Reset the contents and stats of this histogram
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.
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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractHistogram

public AbstractHistogram(long lowestTrackableValue,
                         long highestTrackableValue,
                         int numberOfSignificantValueDigits)

Construct a histogram given the Lowest and Highest values to be tracked and a number of significant decimal digits. Providing a lowestTrackableValue 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 lowestTrackableValue would be 1000.

Parameters:

lowestTrackableValue - 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 * lowestTrackableValue).

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

getTotalCount

public abstract long getTotalCount()

recordValue

public void recordValue(long value)
                 throws ArrayIndexOutOfBoundsException

Record a value in the histogram

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

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:

ArrayIndexOutOfBoundsException - (may throw) if value is exceeds highestTrackableValue

recordValueWithExpectedInterval

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

ArrayIndexOutOfBoundsException - (may throw) if value is exceeds highestTrackableValue

recordValue

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

ArrayIndexOutOfBoundsException - (may throw) if value is exceeds highestTrackableValue

reset

public void reset()

Reset the contents and stats of this histogram

copy

public abstract AbstractHistogram copy()

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

Returns:

A distinct copy of this histogram.

copyCorrectedForCoordinatedOmission

public abstract AbstractHistogram copyCorrectedForCoordinatedOmission(long expectedIntervalBetweenValueSamples)

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

To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, the new histogram will include an auto-generated additional series of decreasingly-smaller (down to the expectedIntervalBetweenValueSamples) value records for each count found in the current histogram that is larger than the expectedIntervalBetweenValueSamples. Note: This is a post-correction method, as opposed to the at-recording correction method provided by recordValueWithExpectedInterval. The two methods are mutually exclusive, and only one of the two should be be used on a given data set to correct for the same coordinated omission issue. by

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

Parameters:

expectedIntervalBetweenValueSamples - 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)

Copy this histogram into the target histogram, overwriting it's contents.

Parameters:

targetHistogram - the histogram to copy into

copyIntoCorrectedForCoordinatedOmission

public void copyIntoCorrectedForCoordinatedOmission(AbstractHistogram targetHistogram,
                                                    long expectedIntervalBetweenValueSamples)

Copy this histogram, corrected for coordinated omission, into the target histogram, overwriting it's contents. (see copyCorrectedForCoordinatedOmission(long) for more detailed explanation about how correction is applied)

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 fromHistogram)
         throws ArrayIndexOutOfBoundsException

Add the contents of another histogram to this one.

Parameters:

fromHistogram - The other histogram.

Throws:

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

addWhileCorrectingForCoordinatedOmission

public void addWhileCorrectingForCoordinatedOmission(AbstractHistogram fromHistogram,
                                                     long expectedIntervalBetweenValueSamples)

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.

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

Throws:

ArrayIndexOutOfBoundsException - (may throw) if values exceed highestTrackableValue

equals

public boolean equals(Object other)

Determine if this histogram is equivalent to another.

Overrides:

equals in class Object

Parameters:

other - the other histogram to compare to

Returns:

True if this histogram are equivalent with the other.

getHistogramData

@Deprecated
public HistogramData getHistogramData()

Deprecated.

Deprecated: All HistogramData has been replaced with direct method calls in AbstractHistogram Provide access to the histogram's data set.

Returns:

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

getLowestTrackableValue

public long getLowestTrackableValue()

get the configured lowestTrackableValue

Returns:

lowestTrackableValue

getHighestTrackableValue

public long getHighestTrackableValue()

get the configured highestTrackableValue

Returns:

highestTrackableValue

getNumberOfSignificantValueDigits

public int getNumberOfSignificantValueDigits()

get the configured numberOfSignificantValueDigits

Returns:

numberOfSignificantValueDigits

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.

getEstimatedFootprintInBytes

public int getEstimatedFootprintInBytes()

Provide a (conservatively high) estimate of the Histogram's total footprint in bytes

Returns:

a (conservatively high) estimate of the Histogram's total footprint in bytes

getStartTimeStamp

public long getStartTimeStamp()

get the start time stamp [optionally] stored with this histogram

Returns:

the start time stamp [optionally] stored with this histogram

setStartTimeStamp

public void setStartTimeStamp(long timeStampMsec)

Set the start time stamp value associated with this histogram to a given value.

Parameters:

timeStampMsec - the value to set the time stamp to, [by convention] in msec since the epoch.

getEndTimeStamp

public long getEndTimeStamp()

get the end time stamp [optionally] stored with this histogram

Returns:

the end time stamp [optionally] stored with this histogram

setEndTimeStamp

public void setEndTimeStamp(long timeStampMsec)

Set the end time stamp value associated with this histogram to a given value.

Parameters:

timeStampMsec - the value to set the time stamp to, [by convention] in msec since the epoch.

getMinValue

public long getMinValue()

Get the lowest recorded value level in the histogram

Returns:

the Min value recorded in the histogram

getMaxValue

public long getMaxValue()

Get the highest recorded value level in the histogram

Returns:

the Max value recorded in the histogram

getMean

public double getMean()

Get the computed mean value of all recorded values in the histogram

Returns:

the mean value (in value units) of the histogram data

getStdDeviation

public double getStdDeviation()

Get the computed standard deviation of all recorded values in the histogram

Returns:

the standard deviation (in value units) of the histogram data

getValueAtPercentile

public long getValueAtPercentile(double percentile)

Get the value at a given percentile

Parameters:

percentile - The percentile for which the return the associated value

Returns:

The value below which a given percentage of the overall recorded value entries in the histogram all fall.

getPercentileAtOrBelowValue

public double getPercentileAtOrBelowValue(long value)

Get the percentile at a given value

Parameters:

value - The value for which the return the associated percentile

Returns:

The percentile of values recorded at or below the given percentage in the histogram all fall.

getCountBetweenValues

public long getCountBetweenValues(long lowValue,
                                  long highValue)
                           throws ArrayIndexOutOfBoundsException

Get the count of recorded values within a range of value levels. (inclusive to within the histogram's resolution)

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 - on values that are outside the tracked value range

getCountAtValue

public long getCountAtValue(long value)
                     throws ArrayIndexOutOfBoundsException

Get the count of recorded values at a specific value

Parameters:

value - The value for which to provide the recorded count

Returns:

The total count of values recorded in the histogram at the given value (to within the histogram resolution at the value level).

Throws:

ArrayIndexOutOfBoundsException - On values that are outside the tracked value range

percentiles

public AbstractHistogram.Percentiles percentiles(int percentileTicksPerHalfDistance)

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.

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(int valueUnitsPerBucket)

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.

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(int valueUnitsInFirstBucket,
                                                                         double logBase)

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.

Parameters:

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

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

Returns:

An Iterable<HistogramIterationValue> through the histogram using a LogarithmicIterator

recordedValues

public AbstractHistogram.RecordedValues recordedValues()

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.

Returns:

An Iterable<HistogramIterationValue> through the histogram using a RecordedValuesIterator

allValues

public AbstractHistogram.AllValues allValues()

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.

Returns:

An Iterable<HistogramIterationValue> through the histogram using a RecordedValuesIterator

outputPercentileDistribution

public void outputPercentileDistribution(PrintStream printStream,
                                         Double outputValueUnitScalingRatio)

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.

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)

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.

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)

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.

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

Get the capacity needed to encode this histogram into a ByteBuffer

Returns:

the capacity needed to encode this histogram into a ByteBuffer

encodeIntoByteBuffer

public int encodeIntoByteBuffer(ByteBuffer buffer)

Encode this histogram into a ByteBuffer

Parameters:

buffer - The buffer to encode into

Returns:

The number of bytes written to the buffer

encodeIntoCompressedByteBuffer

public int encodeIntoCompressedByteBuffer(ByteBuffer targetBuffer,
                                          int compressionLevel)

Encode this histogram in compressed form into a byte array

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)

Encode this histogram in compressed form into a byte array

Parameters:

targetBuffer - The buffer to encode into

Returns:

The number of bytes written to the array

hasOverflowed

public boolean hasOverflowed()

Determine if this histogram had any of it's value counts overflow. Since counts are kept in fixed integer form with potentially limited range (e.g. int and short), a specific value range count could potentially overflow, leading to an inaccurate and misleading histogram representation. This method accurately determines whether or not an overflow condition has happened in an IntHistogram or ShortHistogram.

Returns:

True if this histogram has had a count value overflow.

reestablishTotalCount

public void reestablishTotalCount()

Reestablish the internal notion of totalCount by recalculating it from recorded values. Implementations of AbstractHistogram may maintain a separately tracked notion of totalCount, which is useful for concurrent modification tracking, overflow detection, and speed of execution in iteration. This separately tracked totalCount can get into a state that is inconsistent with the currently recorded value counts under various concurrent modification and overflow conditions. Applying this method will override internal indications of potential overflows and concurrent modification, and will reestablish a self-consistent representation of the histogram data based purely on the current internal representation of recorded counts.

In cases of concurrent modifications such as during copying, or due to racy multi-threaded updates on non-atomic or non-synchronized variants, which can result in potential loss of counts and an inconsistent (indicating potential overflow) internal state, calling this method on a histogram will reestablish a consistent internal state based on the potentially lossy counts representations.

Note that this method is not synchronized against concurrent modification in any way, and will only reliably reestablish consistent internal state when no concurrent modification of the histogram is performed while it executes.

Note that in the cases of actual overflow conditions (which can result in negative counts) this self consistent view may be very wrong, and not just slightly lossy.