public class SingleWriterRecorder extends Object implements ValueRecorder
Histogram
samples from
live recorded data without interrupting or stalling active recording of values. Each interval
histogram provided contains all value counts accumulated since the previous interval histogram
was taken.
This pattern is commonly used in logging interval histogram information while recording is ongoing.
SingleWriterRecorder
expects only a single thread (the "single writer") to
call recordValue(long)
or
recordValueWithExpectedInterval(long, long)
at any point in time.
It DOES NOT safely support concurrent recording calls.
Recording calls are waitfree on architectures that support atomic increment operations, and
re lockfree on architectures that do not.
*
A common pattern for using a SingleWriterRecorder
looks like this:
SingleWriterRecorder recorder = new SingleWriterRecorder(2); // Two decimal point accuracy
Histogram intervalHistogram = null;
...
[start of some loop construct that periodically wants to grab an interval histogram]
...
// Get interval histogram, recycling previous interval histogram:
intervalHistogram = recorder.getIntervalHistogram(intervalHistogram);
histogramLogWriter.outputIntervalHistogram(intervalHistogram);
...
[end of loop construct]
Constructor and Description 

SingleWriterRecorder(int numberOfSignificantValueDigits)
Construct an autoresizing
SingleWriterRecorder with a lowest discernible value of
1 and an autoadjusting highestTrackableValue. 
SingleWriterRecorder(int numberOfSignificantValueDigits,
boolean packed)
Construct an autoresizing
SingleWriterRecorder with a lowest discernible value of
1 and an autoadjusting highestTrackableValue. 
SingleWriterRecorder(long highestTrackableValue,
int numberOfSignificantValueDigits)
Construct a
SingleWriterRecorder given the highest value to be tracked and a number
of significant decimal digits. 
SingleWriterRecorder(long lowestDiscernibleValue,
long highestTrackableValue,
int numberOfSignificantValueDigits)
Construct a
SingleWriterRecorder given the Lowest and highest values to be tracked
and a number of significant decimal digits. 
Modifier and Type  Method and Description 

Histogram 
getIntervalHistogram()
Get a new instance of an interval histogram, which will include a stable, consistent view of all value
counts accumulated since the last interval histogram was taken.

Histogram 
getIntervalHistogram(Histogram histogramToRecycle)
Get an interval histogram, which will include a stable, consistent view of all value counts
accumulated since the last interval histogram was taken.

Histogram 
getIntervalHistogram(Histogram histogramToRecycle,
boolean enforeContainingInstance)
Get an interval histogram, which will include a stable, consistent view of all value counts
accumulated since the last interval histogram was taken.

void 
getIntervalHistogramInto(Histogram targetHistogram)
Place a copy of the value counts accumulated since accumulated (since the last interval histogram
was taken) into
targetHistogram . 
void 
recordValue(long value)
Record a value

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

void 
reset()
Reset any value counts accumulated thus far.

public SingleWriterRecorder(int numberOfSignificantValueDigits, boolean packed)
SingleWriterRecorder
with a lowest discernible value of
1 and an autoadjusting highestTrackableValue. Can autoresize up to track values up to (Long.MAX_VALUE / 2).
Depending on the valuer of the packed
parameter SingleWriterRecorder
can be configuired to
track value counts in a packed internal representation optimized for typical histogram recoded values are
sparse in the value range and tend to be incremented in small unit counts. This packed representation tends
to require significantly smaller amounts of stoarge when compared to unpacked representations, but can incur
additional recording cost due to resizing and repacking operations that may
occur as previously unrecorded values are encountered.
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 nonnegative integer between 0 and 5.packed
 Specifies whether the recorder will uses a packed internal representation or not.public SingleWriterRecorder(int numberOfSignificantValueDigits)
SingleWriterRecorder
with a lowest discernible value of
1 and an autoadjusting highestTrackableValue. Can autoresize up to track values up to (Long.MAX_VALUE / 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 nonnegative integer between 0 and 5.public SingleWriterRecorder(long highestTrackableValue, int numberOfSignificantValueDigits)
SingleWriterRecorder
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.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 nonnegative integer between 0 and 5.public SingleWriterRecorder(long lowestDiscernibleValue, long highestTrackableValue, int numberOfSignificantValueDigits)
SingleWriterRecorder
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.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 nonnegative integer between 0 and 5.public void recordValue(long value)
recordValue
in interface ValueRecorder
value
 the value to recordArrayIndexOutOfBoundsException
 (may throw) if value is exceeds highestTrackableValuepublic void recordValueWithCount(long value, long count) throws ArrayIndexOutOfBoundsException
recordValueWithCount
in interface ValueRecorder
value
 The value to be recordedcount
 The number of occurrences of this value to recordArrayIndexOutOfBoundsException
 (may throw) if value is exceeds highestTrackableValuepublic void recordValueWithExpectedInterval(long value, long expectedIntervalBetweenValueSamples) throws ArrayIndexOutOfBoundsException
To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, Histogram will autogenerate an additional series of decreasinglysmaller (down to the expectedIntervalBetweenValueSamples) value records.
See related notes AbstractHistogram.recordValueWithExpectedInterval(long, long)
for more explanations about coordinated omission and expected interval correction.
*
recordValueWithExpectedInterval
in interface ValueRecorder
value
 The value to recordexpectedIntervalBetweenValueSamples
 If expectedIntervalBetweenValueSamples is larger than 0, add
autogenerated value records as appropriate if value is larger
than expectedIntervalBetweenValueSamplesArrayIndexOutOfBoundsException
 (may throw) if value is exceeds highestTrackableValuepublic Histogram getIntervalHistogram()
Calling getIntervalHistogram()
will reset
the value counts, and start accumulating value counts for the next interval.
public Histogram getIntervalHistogram(Histogram histogramToRecycle)
getIntervalHistogram(histogramToRecycle)
accepts a previously returned interval histogram that can be recycled internally to avoid allocation
and content copying operations, and is therefore significantly more efficient for repeated use than
getIntervalHistogram()
and
getIntervalHistogramInto()
. The provided
histogramToRecycle
must
be either be null or an interval histogram returned by a previous call to
getIntervalHistogram(histogramToRecycle)
or
getIntervalHistogram()
.
NOTE: The caller is responsible for not recycling the same returned interval histogram more than once. If the same interval histogram instance is recycled more than once, behavior is undefined.
Calling getIntervalHistogram(histogramToRecycle)
will reset the value counts, and start
accumulating value counts for the next interval
histogramToRecycle
 a previously returned interval histogram (from this instance of
SingleWriterRecorder
) that may be recycled to avoid allocation and
copy operations.public Histogram getIntervalHistogram(Histogram histogramToRecycle, boolean enforeContainingInstance)
getIntervalHistogram(histogramToRecycle)
accepts a previously returned interval histogram that can be recycled internally to avoid allocation
and content copying operations, and is therefore significantly more efficient for repeated use than
getIntervalHistogram()
and
getIntervalHistogramInto()
. The provided
histogramToRecycle
must
be either be null or an interval histogram returned by a previous call to
getIntervalHistogram(histogramToRecycle)
or
getIntervalHistogram()
.
NOTE: The caller is responsible for not recycling the same returned interval histogram more than once. If the same interval histogram instance is recycled more than once, behavior is undefined.
Calling getIntervalHistogram(histogramToRecycle)
will reset the value counts, and start accumulating value
counts for the next interval
histogramToRecycle
 a previously returned interval histogram that may be recycled to avoid allocation and
copy operations.enforeContainingInstance
 if true, will only allow recycling of histograms previously returned from this
instance of SingleWriterRecorder
. If false, will allow recycling histograms
previously returned by other instances of SingleWriterRecorder
.public void getIntervalHistogramInto(Histogram targetHistogram)
targetHistogram
.
Calling getIntervalHistogramInto(targetHistogram)
will reset
the value counts, and start accumulating value counts for the next interval.targetHistogram
 the histogram into which the interval histogram's data should be copiedpublic void reset()
reset
in interface ValueRecorder
Copyright © 2019. All rights reserved.