Package org.HdrHistogram.packedarray

Class PackedArrayRecorder

java.lang.Object
org.HdrHistogram.packedarray.PackedArrayRecorder
public class PackedArrayRecorder extends Object
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.

PackedArrayRecorder supports fully concurrent increment(int) and add(int, long) calls. While the increment() and add() methods are not quite wait-free, they come "close" to that behavior 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), regardless of the number of operations done.

A common pattern for using a PackedArrayRecorder looks like this: 


 PackedArrayRecorder recorder = new PackedArrayRecorder(); //
 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 Summary

    Constructors
    Constructor
    Description
    PackedArrayRecorder(int virtualLength)
    Construct a PackedArrayRecorder with a given (virtual) array length.
    PackedArrayRecorder(int virtualLength, int initialPhysicalLength)
    Construct a PackedArrayRecorder with a given (virtual) array length, starting with a given initial physical backing store length

  • Method Summary

    Modifier and Type
    Method
    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 enforceContainingInstance)
    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

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • PackedArrayRecorder

      public PackedArrayRecorder(int virtualLength)
      Construct a PackedArrayRecorder with a given (virtual) array length.
      Parameters:
      virtualLength - The (virtual) array length

    • PackedArrayRecorder

      public PackedArrayRecorder(int virtualLength, int initialPhysicalLength)
      Construct a PackedArrayRecorder with a given (virtual) array length, starting with a given initial physical backing store length
      Parameters:
      virtualLength - The (virtual) array length
      initialPhysicalLength - The initial physical backing store length

  • Method Details

    • 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 ArrayIndexOutOfBoundsException
      Increment a value at a given index in the array
      Parameters:
      index - the index of the value to be incremented
      Throws:
      ArrayIndexOutOfBoundsException - (may throw) if value is exceeds length()

    • add

      public void add(int index, long valueToAdd) throws ArrayIndexOutOfBoundsException
      Add to a value at a given index in the array
      Parameters:
      index - The index of value to add to
      valueToAdd - The amount to add to the value at the given index
      Throws:
      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 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.

      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 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.

      Parameters:
      arrayToRecycle - a previously returned interval array (from this instance of PackedArrayRecorder) 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 enforceContainingInstance)
      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 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.

      Parameters:
      arrayToRecycle - a previously returned interval array that may be recycled to avoid allocation and copy operations.
      enforceContainingInstance - if true, will only allow recycling of arrays previously returned from this instance of PackedArrayRecorder. If false, will allow recycling arrays previously returned by other instances of PackedArrayRecorder.
      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.