HdrHistogram 2.1.12 · org.HdrHistogram.packedarray.PackedArraySingleWriterRecorder

Records increments and adds of integer values at indexes of a logical array of 64 bit signed integer values, and provides stable interval 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 PackedArraySingleWriterRecorder#increment(int) or PackedArraySingleWriterRecorder#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]

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	PackedArraySingleWriterRecorder.InternalPackedLongArray

Field Summary

Modifier and Type	Field and Description
private volatile PackedLongArray	activeArray
private final long	instanceId
private static AtomicLong	instanceIdSequencer
private final WriterReaderPhaser	recordingPhaser

Constructor Summary

Access	Constructor and Description
public	PackedArraySingleWriterRecorder(final int The (virtual) array length virtualLength) Construct a `PackedArraySingleWriterRecorder` with a given (virtual) array length.
public	PackedArraySingleWriterRecorder(final int The (virtual) array length virtualLength, final int The initial physical backing store length initialPhysicalLength) Construct a `PackedArraySingleWriterRecorder` with a given (virtual) array length, starting with a given initial physical backing store length

Method Summary

Modifier and Type	Method and Description
public void	add(final int The index of value to add to index, final long The amount to add to the value at the given index valueToAdd) Add to a value at a given index in the array
public synchronized PackedLongArray	Returns: an array containing the values accumulated since the last interval array was taken. getIntervalArray() Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.
public synchronized PackedLongArray	Returns: an array containing the values accumulated since the last interval array was taken. getIntervalArray(final PackedLongArray a previously returned interval array (from this instance of `PackedArraySingleWriterRecorder`) that may be recycled to avoid allocation and copy operations. arrayToRecycle) Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.
public synchronized PackedLongArray	Returns: an array containing the values accumulated since the last interval array was taken. getIntervalArray(final PackedLongArray a previously returned interval array that may be recycled to avoid allocation and copy operations. arrayToRecycle, final boolean 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`. enforeContainingInstance) Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.
public void	increment(final int the index of trhe value to be incremented index) Increment a value at a given index in the array
public int	Returns: The virtual length of the array represented by this recorder length() Returns the virtual length of the array represented by this recorder
private PackedLongArray	performIntervalSample(final PackedLongArray arrayToRecycle)
public synchronized void	reset() Reset the array contents to all zeros.
public void	setVirtualLength(int the new (virtual) length to use newVirtualLength) Change the (virtual) length of the array represented by the this recorder
private void	validateFitAsReplacementArray(final PackedLongArray replacementArray, final boolean enforeContainingInstance)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

activeArray	back to summary
private volatile PackedLongArray activeArray

instanceId	back to summary
private final long instanceId

instanceIdSequencer	back to summary
private static AtomicLong instanceIdSequencer

recordingPhaser	back to summary
private final WriterReaderPhaser recordingPhaser

Constructor Detail

PackedArraySingleWriterRecorder back to summary

PackedArraySingleWriterRecorder	back to summary
public PackedArraySingleWriterRecorder(final int virtualLength) Construct a `PackedArraySingleWriterRecorder` with a given (virtual) array length. Parameters virtualLength:int The (virtual) array length

public PackedArraySingleWriterRecorder(final int virtualLength)

Construct a PackedArraySingleWriterRecorder with a given (virtual) array length.

Parameters

virtualLength:int: The (virtual) array length

PackedArraySingleWriterRecorder back to summary

PackedArraySingleWriterRecorder	back to summary
public PackedArraySingleWriterRecorder(final int virtualLength, final int initialPhysicalLength) Construct a `PackedArraySingleWriterRecorder` with a given (virtual) array length, starting with a given initial physical backing store length Parameters virtualLength:int The (virtual) array length initialPhysicalLength:int The initial physical backing store length

public PackedArraySingleWriterRecorder(final int virtualLength, final int initialPhysicalLength)

Construct a PackedArraySingleWriterRecorder with a given (virtual) array length, starting with a given initial physical backing store length

Parameters

virtualLength:int: The (virtual) array length
initialPhysicalLength:int: The initial physical backing store length

Method Detail

add	back to summary
public void add(final int index, final long valueToAdd) throws ArrayIndexOutOfBoundsException Add to a value at a given index in the array Parameters index:int The index of value to add to valueToAdd:long The amount to add to the value at the given index Exceptions ArrayIndexOutOfBoundsException: (may throw) if value is exceeds length()

add

back to summary

public void add(final int index, final long valueToAdd) throws ArrayIndexOutOfBoundsException

Add to a value at a given index in the array

Parameters

index:int: The index of value to add to
valueToAdd:long: The amount to add to the value at the given index

Exceptions

ArrayIndexOutOfBoundsException:: (may throw) if value is exceeds length()

getIntervalArray back to summary

getIntervalArray	back to summary
public synchronized 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 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 `PackedArraySingleWriterRecorder#getIntervalArray()`. Calling `PackedArraySingleWriterRecorder#getIntervalArray()` will reset the values at all indexes of the array tracked by the recorder, and start accumulating values for the next interval. Returns:PackedLongArray an array containing the values accumulated since the last interval array was taken.

public synchronized 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 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 PackedArraySingleWriterRecorder#getIntervalArray().

Calling PackedArraySingleWriterRecorder#getIntervalArray() will reset the values at all indexes of the array tracked by the recorder, and start accumulating values for the next interval.

Returns:PackedLongArray: an array containing the values accumulated since the last interval array was taken.

getIntervalArray back to summary

getIntervalArray	back to summary
public synchronized PackedLongArray getIntervalArray(final 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 than `PackedArraySingleWriterRecorder#getIntervalArray()`. The provided `arrayToRecycle` must be either be null or an interval array returned by a previous call to `getIntervalArray(arrayToRecycle)` or `PackedArraySingleWriterRecorder#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. Parameters arrayToRecycle:PackedLongArray a previously returned interval array (from this instance of `PackedArraySingleWriterRecorder`) that may be recycled to avoid allocation and copy operations. Returns:PackedLongArray an array containing the values accumulated since the last interval array was taken.

public synchronized PackedLongArray getIntervalArray(final 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 than PackedArraySingleWriterRecorder#getIntervalArray(). The provided arrayToRecycle must be either be null or an interval array returned by a previous call to getIntervalArray(arrayToRecycle) or PackedArraySingleWriterRecorder#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.

Parameters

arrayToRecycle:PackedLongArray: a previously returned interval array (from this instance of PackedArraySingleWriterRecorder) that may be recycled to avoid allocation and copy operations.

Returns:PackedLongArray

an array containing the values accumulated since the last interval array was taken.

getIntervalArray back to summary

getIntervalArray	back to summary
public synchronized PackedLongArray getIntervalArray(final PackedLongArray arrayToRecycle, final 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 than `PackedArraySingleWriterRecorder#getIntervalArray()`. The provided `arrayToRecycle` must be either be null or an interval array returned by a previous call to `getIntervalArray(arrayToRecycle)` or `PackedArraySingleWriterRecorder#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. Parameters arrayToRecycle:PackedLongArray a previously returned interval array that may be recycled to avoid allocation and copy operations. enforeContainingInstance:boolean 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`. Returns:PackedLongArray an array containing the values accumulated since the last interval array was taken.

public synchronized PackedLongArray getIntervalArray(final PackedLongArray arrayToRecycle, final boolean enforeContainingInstance)

Get an interval array, which will include a stable, consistent view of all values accumulated since the last interval array was taken.

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:PackedLongArray: a previously returned interval array that may be recycled to avoid allocation and copy operations.
enforeContainingInstance:boolean: 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.

Returns:PackedLongArray

an array containing the values accumulated since the last interval array was taken.

increment	back to summary
public void increment(final int index) throws ArrayIndexOutOfBoundsException Increment a value at a given index in the array Parameters index:int the index of trhe value to be incremented Exceptions ArrayIndexOutOfBoundsException: (may throw) if value is exceeds length()

increment

back to summary

public void increment(final int index) throws ArrayIndexOutOfBoundsException

Increment a value at a given index in the array

Parameters

index:int: the index of trhe value to be incremented

Exceptions

ArrayIndexOutOfBoundsException:: (may throw) if value is exceeds length()

length	back to summary
public int length() Returns the virtual length of the array represented by this recorder Returns:int The virtual length of the array represented by this recorder

length

back to summary

public int length()

Returns the virtual length of the array represented by this recorder

Returns:int: The virtual length of the array represented by this recorder

performIntervalSample	back to summary
private PackedLongArray performIntervalSample(final PackedLongArray arrayToRecycle)

reset	back to summary
public synchronized void reset() Reset the array contents to all zeros.

setVirtualLength	back to summary
public void setVirtualLength(int newVirtualLength) Change the (virtual) length of the array represented by the this recorder Parameters newVirtualLength:int the new (virtual) length to use

setVirtualLength

back to summary

public void setVirtualLength(int newVirtualLength)

Change the (virtual) length of the array represented by the this recorder

Parameters

newVirtualLength:int: the new (virtual) length to use

validateFitAsReplacementArray	back to summary
private void validateFitAsReplacementArray(final PackedLongArray replacementArray, final boolean enforeContainingInstance)

public Class PackedArraySingleWriterRecorder

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class PackedArraySingleWriterRecorder.InternalPackedLongArray

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Access	Constructor and Description
private	InternalPackedLongArray(final long id, int virtualLength, final int initialPhysicalLength)
private	InternalPackedLongArray(final long id, final int virtualLength)