Class PackedArrayRecorder


  • public class PackedArrayRecorder
    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 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 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 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]
     
    • Field Detail

      • instanceIdSequencer

        private static java.util.concurrent.atomic.AtomicLong instanceIdSequencer
      • instanceId

        private final long instanceId
    • Constructor Detail

      • 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 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 to
        valueToAdd - 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 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 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 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.
        enforeContainingInstance - 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.
      • validateFitAsReplacementArray

        private void validateFitAsReplacementArray​(PackedLongArray replacementArray,
                                                   boolean enforeContainingInstance)