Package io.deephaven.base.ringbuffer

Class AggregatingObjectRingBuffer<T>

java.lang.Object
io.deephaven.base.ringbuffer.AggregatingObjectRingBuffer<T>
public class AggregatingObjectRingBuffer<T> extends Object
A ring buffer which aggregates its contents according to a user-defined aggregation function. This aggregation calculation is performed lazily, when the user calls evaluate(). Internally the class manages a tree of intermediate aggregation values. This allows the class to efficiently update the final aggregated value when entries enter and leave the buffer, without necessarily running the calculation over the whole buffer.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    AggregatingObjectRingBuffer.ObjectFunction<T>
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    AggregatingObjectRingBuffer(int capacity, T identityVal, @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggFunction)
    Creates a ring buffer for T values which aggregates its contents according to a user-defined aggregation function.
    AggregatingObjectRingBuffer(int capacity, T identityVal, @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggTreeFunction, @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggInitialFunction)
    Creates a ring buffer for T values which aggregates its contents according to a user-defined aggregation function.
    AggregatingObjectRingBuffer(int capacity, T identityVal, @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggTreeFunction, @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggInitialFunction, boolean growable)
    Creates a ring buffer for T values which aggregates its contents according to a user-defined aggregation function.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(T e)
    Adds an entry to the ring buffer.
    void
    addIdentityValue()
    Adds the identity element to the ring buffer.
    T
    addOverwrite(T e, T notFullResult)
    Adds an entry to the ring buffer.
    void
    addUnsafe(T e)
    Adds a value without overflow detection.
    T
    back()
    Returns the element at the tail of the ring buffer
    int
    capacity()
     
    void
    clear()
    Removes all elements from the ring buffer and resets the data structure.
    T
    element()
    Returns the element at the head of the ring buffer if the ring buffer is non-empty.
    void
    ensureRemaining(int count)
    Ensures that there is sufficient empty space to store count additional items in the buffer.
    T
    evaluate()
    Return the result of aggregation function applied to the contents of the aggregating ring buffer.
    T
    front()
    Returns the element at the head of the ring buffer
    T
    front(int offset)
    Returns the element at the specified offset from the head in the ring buffer.
    T[]
    getAll()
    Returns an array containing all elements in the ring buffer.
    protected void
    grow(int increase)
    Increases the capacity of the aggregating ring buffer.
    boolean
    isEmpty()
     
    boolean
    isFull()
     
    boolean
    offer(T e)
    Attempts to add an entry to the ring buffer.
    T
    peek(T onEmpty)
    Returns the element at the head of the ring buffer if the ring buffer is non-empty.
    T
    peekBack(T onEmpty)
    Returns the element at the tail of the ring buffer if the ring buffer is non-empty.
    T
    poll(T onEmpty)
    Removes the element at the head of the ring buffer if the ring buffer is non-empty.
    int
    remaining()
     
    T
    remove()
    Removes one element from the head of the ring buffer.
    T[]
    remove(int count)
    Removes multiple elements from the front of the ring buffer and returns the items as an array.
    T
    removeUnsafe()
    Removes an element without empty buffer detection.
    int
    size()
     

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • AggregatingObjectRingBuffer

      public AggregatingObjectRingBuffer(int capacity, T identityVal, @NotNull @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggFunction)
      Creates a ring buffer for T values which aggregates its contents according to a user-defined aggregation function. This aggregation calculation is performed lazily, when the user calls evaluate(). Internally the class manages a tree of intermediate aggregation values. This allows the class to efficiently update the final aggregated value when entries enter and leave the buffer, without necessarily running the calculation over the whole buffer.

      The buffer expands its capacity as needed, employing a capacity-doubling strategy. However, note that the data structure never gives back storage: i.e. its capacity never shrinks.

      Parameters:
      capacity - the minimum size for the structure to hold
      identityVal - The identity value associated with the aggregation function. This is a value e that satisfies f(x,e) == x and f(e,x) == x for all x. For example, for the AggregatingFloatRingBuffer, if the aggFunction is addition, multiplication, Math.min, or Math.max, the corresponding identity values would be 0.0f, 1.0f, Float.MAX_VALUE, and -Float.MAX_VALUE respectively.
      aggFunction - A function used to aggregate the data in the ring buffer. The function must be associative: that is it must satisfy f(f(a, b), c) == f(a, f(b, c)). For example, addition is associative, because (a + b) + c == a + (b + c). Some examples of associative functions are addition, multiplication, Math.min(), and Math.max(). This data structure maintains a tree of partially-evaluated subranges of the data, combining them efficiently whenever the data changes.

    • AggregatingObjectRingBuffer

      public AggregatingObjectRingBuffer(int capacity, T identityVal, @NotNull @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggTreeFunction, @NotNull @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggInitialFunction)
      Creates a ring buffer for T values which aggregates its contents according to a user-defined aggregation function. This aggregation calculation is performed lazily, when the user calls evaluate(). Internally the class manages a tree of intermediate aggregation values. This allows the class to efficiently update the final aggregated value when entries enter and leave the buffer, without necessarily running the calculation over the whole buffer.

      The buffer expands its capacity as needed, employing a capacity-doubling strategy. However, note that the data structure never gives back storage: i.e. its capacity never shrinks.

      Parameters:
      capacity - the minimum size for the structure to hold
      identityVal - The identity value associated with the aggregation function. This is a value e that satisfies f(x,e) == x and f(e,x) == x for all x. For example, for the AggregatingFloatRingBuffer, if the aggFunction is addition, multiplication, Math.min, or Math.max, the corresponding identity values would be 0.0f, 1.0f, Float.MAX_VALUE, and -Float.MAX_VALUE respectively.
      aggTreeFunction - A function used to aggregate the data in the ring buffer. The function must be associative: that is it must satisfy f(f(a, b), c) == f(a, f(b, c)). For example, addition is associative, because (a + b) + c == a + (b + c). Some examples of associative functions are addition, multiplication, Math.min(), and Math.max(). This data structure maintains a tree of partially-evaluated subranges of the data, combining them efficiently whenever the data changes.
      aggInitialFunction - An associative function separate from aggTreeFunction to be applied only to the user-supplied values in the ring buffer. The results of this function will be populated into the tree for later evaluation by aggTreeFunction. This function could be used to filter or translate data values at the leaf of the tree without affecting later computation.

    • AggregatingObjectRingBuffer

      public AggregatingObjectRingBuffer(int capacity, T identityVal, @NotNull @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggTreeFunction, @NotNull @NotNull AggregatingObjectRingBuffer.ObjectFunction<T> aggInitialFunction, boolean growable)
      Creates a ring buffer for T values which aggregates its contents according to a user-defined aggregation function. This aggregation calculation is performed lazily, when the user calls evaluate(). Internally the class manages a tree of intermediate aggregation values. This allows the class to efficiently update the final aggregated value when entries enter and leave the buffer, without necessarily running the calculation over the whole buffer.

      If growable = true, the buffer expands its capacity as needed, employing a capacity-doubling strategy. However, note that the data structure never gives back storage: i.e. its capacity never shrinks.

      Parameters:
      capacity - the minimum size for the structure to hold
      identityVal - The identity value associated with the aggregation function. This is a value e that satisfies f(x,e) == x and f(e,x) == x for all x. For example, for the AggregatingFloatRingBuffer, if the aggFunction is addition, multiplication, Math.min, or Math.max, the corresponding identity values would be 0.0f, 1.0f, Float.MAX_VALUE, and -Float.MAX_VALUE respectively.
      aggTreeFunction - A function used to aggregate the data in the ring buffer. The function must be associative: that is it must satisfy f(f(a, b), c) == f(a, f(b, c)). For example, addition is associative, because (a + b) + c == a + (b + c). Some examples of associative functions are addition, multiplication, Math.min(), and Math.max(). This data structure maintains a tree of partially-evaluated subranges of the data, combining them efficiently whenever the data changes.
      aggInitialFunction - An associative function separate from aggTreeFunction to be applied only to the user-supplied values in the ring buffer. The results of this function will be populated into the tree for later evaluation by aggTreeFunction. This function could be used to filter or translate data values at the leaf of the tree without affecting later computation.
      growable - whether to allow growth when the buffer is full.

  • Method Details

    • grow

      protected void grow(int increase)
      Increases the capacity of the aggregating ring buffer.
      Parameters:
      increase - Increase amount. The ring buffer's capacity will be increased by at least this amount.

    • isFull

      public boolean isFull()

    • isEmpty

      public boolean isEmpty()

    • size

      public int size()

    • capacity

      public int capacity()

    • remaining

      public int remaining()

    • add

      public void add(T e)
      Adds an entry to the ring buffer. Throws an exception if buffer is full and growth is disabled. For a graceful failure, use offer(Object)
      Parameters:
      e - the Object to be added to the buffer
      Throws:
      UnsupportedOperationException - when growable is false and buffer is full

    • ensureRemaining

      public void ensureRemaining(int count)
      Ensures that there is sufficient empty space to store count additional items in the buffer. If the buffer is growable, this may result in an internal growth operation. This call should be used in conjunction with addUnsafe(Object).
      Parameters:
      count - the minimum number of empty entries in the buffer after this call
      Throws:
      UnsupportedOperationException - when growable is false and the buffer's available space is less than count

    • addOverwrite

      public T addOverwrite(T e, T notFullResult)
      Adds an entry to the ring buffer. If the buffer is full, overwrites the oldest entry with the new one.
      Parameters:
      e - the Object to be added to the buffer
      notFullResult - value to return if the buffer is not full
      Returns:
      the overwritten entry if the buffer is full, the provided value otherwise

    • offer

      public boolean offer(T e)
      Attempts to add an entry to the ring buffer. If the buffer is full, the add fails and the buffer will not grow even if growable.
      Parameters:
      e - the Object to be added to the buffer
      Returns:
      true if the value was added successfully, false otherwise

    • remove

      public T remove()
      Removes one element from the head of the ring buffer.
      Returns:
      The removed element if the ring buffer was non-empty
      Throws:
      NoSuchElementException - if the buffer is empty

    • poll

      public T poll(T onEmpty)
      Removes the element at the head of the ring buffer if the ring buffer is non-empty. Otherwise returns onEmpty.
      Parameters:
      onEmpty - the value to return if the ring buffer is empty
      Returns:
      The removed element if the ring buffer was non-empty, otherwise the value of onEmpty.

    • element

      public T element()
      Returns the element at the head of the ring buffer if the ring buffer is non-empty.
      Returns:
      The head element if the ring buffer is non-empty
      Throws:
      NoSuchElementException - if the buffer is empty

    • peek

      public T peek(T onEmpty)
      Returns the element at the head of the ring buffer if the ring buffer is non-empty. Otherwise returns onEmpty.
      Parameters:
      onEmpty - the value to return if the ring buffer is empty
      Returns:
      The head element if the ring buffer is non-empty

    • front

      public T front()
      Returns the element at the head of the ring buffer
      Returns:
      The element at the head of the ring buffer
      Throws:
      NoSuchElementException - if the buffer is empty

    • front

      public T front(int offset)
      Returns the element at the specified offset from the head in the ring buffer.
      Parameters:
      offset - The specified offset.
      Returns:
      The element at the specified offset
      Throws:
      NoSuchElementException - if the buffer is empty

    • back

      public T back()
      Returns the element at the tail of the ring buffer
      Returns:
      The element at the tail of the ring buffer
      Throws:
      NoSuchElementException - if the buffer is empty

    • peekBack

      public T peekBack(T onEmpty)
      Returns the element at the tail of the ring buffer if the ring buffer is non-empty. Otherwise returns onEmpty.
      Parameters:
      onEmpty - the value to return if the ring buffer is empty
      Returns:
      The element at the tail of the ring buffer, otherwise the value of onEmpty.

    • getAll

      public T[] getAll()
      Returns an array containing all elements in the ring buffer.
      Returns:
      An array containing a copy of the elements in the ring buffer.

    • addUnsafe

      public void addUnsafe(T e)
      Adds a value without overflow detection. The caller must ensure that there is at least one element of free space in the ring buffer before calling this method. The caller may use ensureRemaining(int) or remaining() for this purpose.
      Parameters:
      e - the value to add to the buffer

    • addIdentityValue

      public void addIdentityValue()
      Adds the identity element to the ring buffer. Throws an exception if the buffer is full and not growable.
      Throws:
      UnsupportedOperationException - when growable is false and buffer is full

    • removeUnsafe

      public T removeUnsafe()
      Removes an element without empty buffer detection. The caller must ensure that there is at least one element in the ring buffer. The size() method may be used for this purpose.
      Returns:
      the value removed from the buffer

    • remove

      public T[] remove(int count)
      Removes multiple elements from the front of the ring buffer and returns the items as an array.
      Parameters:
      count - The number of elements to remove.
      Throws:
      NoSuchElementException - if the buffer is empty

    • clear

      public void clear()
      Removes all elements from the ring buffer and resets the data structure. This may require resetting all entries in the storage buffer and evaluation tree and should be considered to be of complexity O(capacity) instead of O(size).

    • evaluate

      public T evaluate()
      Return the result of aggregation function applied to the contents of the aggregating ring buffer.
      Returns:
      The result of (@code aggFunction()} applied to each value in the buffer