Package org.evoludo.util

Class RingBuffer<T>

Object
RingBuffer<T>
Type Parameters:
T - data type of buffer
All Implemented Interfaces:
Iterable<T>
public class RingBuffer<T> extends Object implements Iterable<T>
Non-blocking ring buffer. Entries can be added continuously but only the most recent entries are retained up to the buffers capacity. This is useful to retain, for example, the most recent entries of a time series.

Note: arrays, primitives and java generics don't play well together, which necessitates specialized instances of RingBuffer. In particular, subclasses don't work either, which results in code redundancy in the different implementations.

Author:
Christoph Hauert

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private class 
    RingBuffer.BckItr
    Iterates backwards over all elements in this buffer starting with the most recent entry.
    private class 
    RingBuffer.FwdItr
    Iterates forward over all elements in this buffer starting with the oldest entry.
    private class 
    RingBuffer.LstItr
    Iterates forward over all elements in this buffer starting with the oldest entry.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) ArrayList<T>
    buffer
    Array to hold buffer of T objects.
    (package private) int
    bufferCapacity
    Buffer capacity, i.e.
    (package private) int
    bufferDepth
    The depth of a buffer containing arrays.
    (package private) int
    bufferPtr
    Index of most recently added element in buffer.

  • Constructor Summary

    Constructors
    Constructor
    Description
    RingBuffer(int capacity)
    Create new ring buffer for storing up to capacity entries.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    append(T entry)
    Append new entry to ring buffer.
    protected int
    arrayLength(T entry)
    Helper method to deal with entry representing an array.
    void
    clear()
    Remove all entries from ring buffer.
    T
    first()
    Return first/oldest buffer entry.
    T
    get(int index)
    Retrieve buffer entry at position index (without removing it).
    int
    getCapacity()
    Get the capacity of the ring buffer.
    int
    getDepth()
    Get the depth of array entries.
    int
    getSize()
    Get the number of entries in the ring buffer.
    boolean
    isEmpty()
    Check if the ring buffer is empty.
    boolean
    isFull()
    Check if the ring buffer is at capacity.
    Iterator<T>
    iterator()
     
    T
    last()
    Return last/most recent buffer entry.
    ListIterator<T>
    listIterator()
    Returns a list iterator over all elements in this buffer in chronological order.
    ListIterator<T>
    listIterator(int index)
    Returns a list iterator over all elements in this buffer in chronological order starting with entry at index.
    Iterator<T>
    ordered()
    Returns an iterator over all elements in this buffer in chronological order.
    T
    replace(int index, T entry)
    Replace buffer entry at position index with entry.
    T
    replace(T entry)
    Replace most recent entry in ring buffer with entry.
    void
    setCapacity(int capacity)
    Set maximum number of entries in ring buffer to capacity.

    Methods inherited from class Object

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

    Methods inherited from interface Iterable

    forEach, spliterator

  • Field Details

    • buffer

      ArrayList<T> buffer
      Array to hold buffer of T objects.

    • bufferPtr

      int bufferPtr
      Index of most recently added element in buffer.

    • bufferCapacity

      int bufferCapacity
      Buffer capacity, i.e. the maximum number of elements the buffer can contain.

    • bufferDepth

      int bufferDepth
      The depth of a buffer containing arrays.
      • &gt;0: length of array entries
      • 0: entries are objects (not arrays)
      • -1: entries are arrays of different lengths
      • -2: buffer is mixture of objects and arrays

  • Constructor Details

  • Method Details

    • setCapacity

      public void setCapacity(int capacity) throws IllegalArgumentException
      Set maximum number of entries in ring buffer to capacity. If the current buffer size exceeds the new capacity then entries with indices capacity through size-1 are discarded. After setting the capacity the size of the buffer is at most capacity.
      Parameters:
      capacity - maximum number of entries
      Throws:
      IllegalArgumentException - if capacity≤0

    • getCapacity

      public int getCapacity()
      Get the capacity of the ring buffer. The capacity is the maximum number of entries the buffer can hold.
      Returns:
      the capacity of the ring buffer

    • getDepth

      public int getDepth()
      Get the depth of array entries.
      Returns:
      • &gt;0: length of array entries
      • 0: entries are objects (not arrays)
      • -1: entries are arrays of different lengths
      • -2: buffer is mixture of objects and arrays

    • getSize

      public int getSize()
      Get the number of entries in the ring buffer.
      Returns:
      the number of entries

    • isEmpty

      public boolean isEmpty()
      Check if the ring buffer is empty.
      Returns:
      true if ring buffer is empty

    • isFull

      public boolean isFull()
      Check if the ring buffer is at capacity.
      Returns:
      true if ring buffer is at capacity

    • clear

      public void clear()
      Remove all entries from ring buffer. Reset buffer size to zero.

    • append

      public void append(T entry)
      Append new entry to ring buffer. If buffer is at capacity, the oldest entry is removed.

      Important:

      Must create copy of data/array for adding to buffer. Otherwise, any subsequent changes to the data will also change the buffer. Copying of the entry cannot be reliably done in RingBuffer without reflection or other trickery.
      Parameters:
      entry - to add to buffer
      See Also:

    • arrayLength

      protected int arrayLength(T entry)
      Helper method to deal with entry representing an array. Returns the length of the array or -1 if it is not an array.
      Parameters:
      entry - the buffer entry
      Returns:
      the length of the array or -1 if entry is not an array
      Throws:
      IllegalArgumentException - if unable to determine array type of entry

    • get

      public T get(int index) throws IllegalArgumentException
      Retrieve buffer entry at position index (without removing it). The most recently added entry has index 0, the one before index 1, etc. up the buffer size-1 (or its capacity-1, if the buffer is at capacity).
      Parameters:
      index - of entry to retrieve
      Returns:
      buffer entry
      Throws:
      IllegalArgumentException - if index<0 or index>size-1.

    • first

      public T first()
      Return first/oldest buffer entry.
      Returns:
      first buffer entry or null if buffer is empty

    • last

      public T last()
      Return last/most recent buffer entry.
      Returns:
      first buffer entry or null if buffer is empty

    • replace

      public T replace(int index, T entry) throws IllegalArgumentException
      Replace buffer entry at position index with entry. Return old entry at position index. The most recently added entry has index 0, the one before index 1, etc. up the buffer size-1 (or its capacity-1, if the buffer is at capacity).

      Important:

      Must create copy of data/array for including in buffer. Otherwise, any subsequent changes to the data will also change the buffer. Copying of the entry cannot be reliably done in RingBuffer without reflection or other trickery.
      Parameters:
      index - of entry to replace
      entry - replacement
      Returns:
      previous buffer entry
      Throws:
      IllegalArgumentException - if index<0 or index>size-1.
      See Also:

    • replace

      public T replace(T entry)
      Replace most recent entry in ring buffer with entry.

      Important:

      Must create copy of data/array for including in buffer. Otherwise, any subsequent changes to the data will also change the buffer. Copying of the entry cannot be reliably done in RingBuffer without reflection or other trickery.
      Parameters:
      entry - replacement
      Returns:
      previous buffer entry
      See Also:

    • iterator

      public Iterator<T> iterator()
      Specified by:
      iterator in interface Iterable<T>

    • ordered

      public Iterator<T> ordered()
      Returns an iterator over all elements in this buffer in chronological order.
      Returns:
      the forward iterator

    • listIterator

      public ListIterator<T> listIterator()
      Returns a list iterator over all elements in this buffer in chronological order.
      Returns:
      the forward list iterator

    • listIterator

      public ListIterator<T> listIterator(int index)
      Returns a list iterator over all elements in this buffer in chronological order starting with entry at index.
      Parameters:
      index - the index of the first element to be returned
      Returns:
      the forward list iterator