Package org.HdrHistogram.packedarray

Class PackedArraySingleWriterRecorder

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

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

    • PackedArraySingleWriterRecorder

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

    • PackedArraySingleWriterRecorder

      public PackedArraySingleWriterRecorder(int virtualLength, int initialPhysicalLength)
      Construct a PackedArraySingleWriterRecorder 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 PackedArraySingleWriterRecorder) 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 PackedArraySingleWriterRecorder. If false, will allow recycling arrays previously returned by other instances of PackedArraySingleWriterRecorder.
      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.