Class PackedArraySingleWriterRecorder
- java.lang.Object
-
- org.HdrHistogram.packedarray.PackedArraySingleWriterRecorder
-
public class PackedArraySingleWriterRecorder extends java.lang.Object
Records increments and adds of integer values at indexes of a logical array of 64 bit signed integer values, and provides stable intervalPackedLongArray
samples from live recorded data without interrupting or stalling active recording of values. Each interval array provided contains all values accumulated since the previous interval array was taken.This pattern is commonly used in logging interval accumulator information while recording is ongoing.
PackedArraySingleWriterRecorder
expects only a single thread (the "single writer") to callincrement(int)
oradd(int, long)
at any point in time. It DOES NOT safely support concurrent increment or add calls. While theincrement()
andadd()
methods are not quite wait-free, they come "close" to that behvaior in the sense that a given thread will incur a total of no more than a capped fixed number (e.g. 74 in a current implementation) of non-wait-free add or increment operations during the lifetime of an interval array (including across recycling of that array across intervals within the same recorder), regradless of the number of operations done.A common pattern for using a
PackedArraySingleWriterRecorder
looks like this:PackedArraySingleWriterRecorder recorder = new PackedArraySingleWriterRecorder(); // PackedLongArray intervalArray = null; ... [start of some loop construct that periodically wants to grab an interval array] ... // Get interval array, recycling previous interval array: intervalArray = recorder.getIntervalArray(intervalArray); // Process the interval array, which is nice and stable here: myLogWriter.logArrayContents(intervalArray); ... [end of loop construct]
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
PackedArraySingleWriterRecorder.InternalPackedLongArray
-
Field Summary
Fields Modifier and Type Field Description private PackedLongArray
activeArray
private long
instanceId
private static java.util.concurrent.atomic.AtomicLong
instanceIdSequencer
private WriterReaderPhaser
recordingPhaser
-
Constructor Summary
Constructors Constructor Description PackedArraySingleWriterRecorder(int virtualLength)
Construct aPackedArraySingleWriterRecorder
with a given (virtual) array length.PackedArraySingleWriterRecorder(int virtualLength, int initialPhysicalLength)
Construct aPackedArraySingleWriterRecorder
with a given (virtual) array length, starting with a given initial physical backing store length
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
add(int index, long valueToAdd)
Add to a value at a given index in the arrayPackedLongArray
getIntervalArray()
Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.PackedLongArray
getIntervalArray(PackedLongArray arrayToRecycle)
Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.PackedLongArray
getIntervalArray(PackedLongArray arrayToRecycle, boolean enforeContainingInstance)
Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.void
increment(int index)
Increment a value at a given index in the arrayint
length()
Returns the virtual length of the array represented by this recorderprivate PackedLongArray
performIntervalSample(PackedLongArray arrayToRecycle)
void
reset()
Reset the array contents to all zeros.void
setVirtualLength(int newVirtualLength)
Change the (virtual) length of the array represented by the this recorderprivate void
validateFitAsReplacementArray(PackedLongArray replacementArray, boolean enforeContainingInstance)
-
-
-
Field Detail
-
instanceIdSequencer
private static java.util.concurrent.atomic.AtomicLong instanceIdSequencer
-
instanceId
private final long instanceId
-
recordingPhaser
private final WriterReaderPhaser recordingPhaser
-
activeArray
private volatile PackedLongArray activeArray
-
-
Constructor Detail
-
PackedArraySingleWriterRecorder
public PackedArraySingleWriterRecorder(int virtualLength)
Construct aPackedArraySingleWriterRecorder
with a given (virtual) array length.- Parameters:
virtualLength
- The (virtual) array length
-
PackedArraySingleWriterRecorder
public PackedArraySingleWriterRecorder(int virtualLength, int initialPhysicalLength)
Construct aPackedArraySingleWriterRecorder
with a given (virtual) array length, starting with a given initial physical backing store length- Parameters:
virtualLength
- The (virtual) array lengthinitialPhysicalLength
- The initial physical backing store length
-
-
Method Detail
-
length
public int length()
Returns the virtual length of the array represented by this recorder- Returns:
- The virtual length of the array represented by this recorder
-
setVirtualLength
public void setVirtualLength(int newVirtualLength)
Change the (virtual) length of the array represented by the this recorder- Parameters:
newVirtualLength
- the new (virtual) length to use
-
increment
public void increment(int index) throws java.lang.ArrayIndexOutOfBoundsException
Increment a value at a given index in the array- Parameters:
index
- the index of trhe value to be incremented- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if value is exceeds length()
-
add
public void add(int index, long valueToAdd) throws java.lang.ArrayIndexOutOfBoundsException
Add to a value at a given index in the array- Parameters:
index
- The index of value to add tovalueToAdd
- The amount to add to the value at the given index- Throws:
java.lang.ArrayIndexOutOfBoundsException
- (may throw) if value is exceeds length()
-
getIntervalArray
public PackedLongArray getIntervalArray()
Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.Calling this method is equivalent to calling
getIntervalArray(null)
. It is generally recommended that thegetIntervalHistogram(arrayToRecycle)
orm be used for regular interval array sampling, as that form accepts a previously returned interval array that can be recycled internally to avoid allocation and content copying operations, and is therefore significantly more efficient for repeated use thangetIntervalArray()
.Calling
getIntervalArray()
will reset the values at all indexes of the array tracked by the recorder, and start accumulating values for the next interval.- Returns:
- an array containing the values accumulated since the last interval array was taken.
-
getIntervalArray
public PackedLongArray getIntervalArray(PackedLongArray arrayToRecycle)
Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.getIntervalArray(arrayToRecycle)
accepts a previously returned interval array that can be recycled internally to avoid allocation and content copying operations, and is therefore significantly more efficient for repeated use thangetIntervalArray()
. The providedarrayToRecycle
must be either be null or an interval array returned by a previous call togetIntervalArray(arrayToRecycle)
orgetIntervalArray()
.NOTE: The caller is responsible for not recycling the same returned interval array more than once. If the same interval array instance is recycled more than once, behavior is undefined.
Calling
getIntervalArray(arrayToRecycle)
will reset the values at all indexes of the array tracked by the recorder, and start accumulating values for the next interval.- Parameters:
arrayToRecycle
- a previously returned interval array (from this instance ofPackedArraySingleWriterRecorder
) that may be recycled to avoid allocation and copy operations.- Returns:
- an array containing the values accumulated since the last interval array was taken.
-
getIntervalArray
public PackedLongArray getIntervalArray(PackedLongArray arrayToRecycle, boolean enforeContainingInstance)
Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.getIntervalArray(arrayToRecycle)
accepts a previously returned interval array that can be recycled internally to avoid allocation and content copying operations, and is therefore significantly more efficient for repeated use thangetIntervalArray()
. The providedarrayToRecycle
must be either be null or an interval array returned by a previous call togetIntervalArray(arrayToRecycle)
orgetIntervalArray()
.NOTE: The caller is responsible for not recycling the same returned interval array more than once. If the same interval array instance is recycled more than once, behavior is undefined.
Calling
getIntervalArray(arrayToRecycle, enforeContainingInstance)
will reset the values at all indexes of the array tracked by the recorder, and start accumulating values for the next interval.- Parameters:
arrayToRecycle
- a previously returned interval array that may be recycled to avoid allocation and copy operations.enforeContainingInstance
- if true, will only allow recycling of arrays previously returned from this instance ofPackedArraySingleWriterRecorder
. If false, will allow recycling arrays previously returned by other instances ofPackedArraySingleWriterRecorder
.- Returns:
- an array containing the values accumulated since the last interval array was taken.
-
reset
public void reset()
Reset the array contents to all zeros.
-
performIntervalSample
private PackedLongArray performIntervalSample(PackedLongArray arrayToRecycle)
-
validateFitAsReplacementArray
private void validateFitAsReplacementArray(PackedLongArray replacementArray, boolean enforeContainingInstance)
-
-