public class PackedArraySingleWriterRecorder extends Object
PackedLongArray
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 call
increment(int)
or
add(int, long)
at any point in time.
It DOES NOT safely support concurrent increment or add calls.
While the increment()
and add()
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]
Constructor and Description |
---|
PackedArraySingleWriterRecorder(int virtualLength)
Construct a
PackedArraySingleWriterRecorder with a given (virtual) array length. |
PackedArraySingleWriterRecorder(int virtualLength,
int initialPhysicalLength)
Construct a
PackedArraySingleWriterRecorder with a given (virtual) array length, starting with a given
initial physical backing store length |
Modifier and Type | Method and Description |
---|---|
void |
add(int index,
long valueToAdd)
Add to a value at a given index in the array
|
PackedLongArray |
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 array
|
int |
length()
Returns the virtual length of the array represented by this recorder
|
void |
reset()
Reset the array contents to all zeros.
|
void |
setVirtualLength(int newVirtualLength)
Change the (virtual) length of the array represented by the this recorder
|
public PackedArraySingleWriterRecorder(int virtualLength)
PackedArraySingleWriterRecorder
with a given (virtual) array length.virtualLength
- The (virtual) array lengthpublic PackedArraySingleWriterRecorder(int virtualLength, int initialPhysicalLength)
PackedArraySingleWriterRecorder
with a given (virtual) array length, starting with a given
initial physical backing store lengthvirtualLength
- The (virtual) array lengthinitialPhysicalLength
- The initial physical backing store lengthpublic int length()
public void setVirtualLength(int newVirtualLength)
newVirtualLength
- the new (virtual) length to usepublic void increment(int index) throws ArrayIndexOutOfBoundsException
index
- the index of trhe value to be incrementedArrayIndexOutOfBoundsException
- (may throw) if value is exceeds length()public void add(int index, long valueToAdd) throws ArrayIndexOutOfBoundsException
index
- The index of value to add tovalueToAdd
- The amount to add to the value at the given indexArrayIndexOutOfBoundsException
- (may throw) if value is exceeds length()public PackedLongArray getIntervalArray()
Calling this method is equivalent to calling getIntervalArray(null)
. It is generally recommended
that the getIntervalHistogram(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 than getIntervalArray()
.
Calling getIntervalArray()
will reset the values at
all indexes of the array tracked by the recorder, and start accumulating values for the next interval.
public PackedLongArray getIntervalArray(PackedLongArray arrayToRecycle)
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 than
getIntervalArray()
. The provided arrayToRecycle
must
be either be null or an interval array returned by a previous call to
getIntervalArray(arrayToRecycle)
or
getIntervalArray()
.
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.
arrayToRecycle
- a previously returned interval array (from this instance of
PackedArraySingleWriterRecorder
) that may be recycled to avoid allocation and
copy operations.public PackedLongArray getIntervalArray(PackedLongArray arrayToRecycle, boolean enforeContainingInstance)
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 than
getIntervalArray()
. The provided arrayToRecycle
must
be either be null or an interval array returned by a previous call to
getIntervalArray(arrayToRecycle)
or
getIntervalArray()
.
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.
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 of PackedArraySingleWriterRecorder
. If false, will allow recycling arrays
previously returned by other instances of PackedArraySingleWriterRecorder
.public void reset()
Copyright © 2019. All rights reserved.