Package net.sherst.util

Class BlockingRingBuffer<E>

java.lang.Object
net.sherst.util.FastRingBuffer<E>
net.sherst.util.SafeRingBuffer<E>
net.sherst.util.BlockingRingBuffer<E>
Type Parameters:
E - the type of elements in the buffer
public class BlockingRingBuffer<E> extends SafeRingBuffer<E>
A modified (blocking) thread-safe ring buffer (circular buffer) implementation for Java.

The add(E) and addAll(E[]) methods block until there is space in the buffer. The remove() and remove(int,java.lang.Class<E>) methods block until there are enough elements in the buffer. The offer(E) and poll() methods (and variants) do not block.

A ring buffer is a fixed-size first in - first out buffer typically backed by an array with head and tail pointers. Elements are added to the tail of the buffer and removed from the head. When the end of the array is reached, the pointers wrap around to the beginning. When the buffer is full, adding new elements overwrites the oldest elements (but see the offer(E) and offer(E[]) methods in this implementation).

Pros: Fast, simple.

Cons: Size fixed at creation time, adding new elements overwrites the oldest ones if the buffer is full, elements can only be added or removed in FIFO order.

There are some useful look-ahead methods, peek(), peek(int), at(E), at(E[]), atSkip(E) and atSkip(E[]).

These are simple, hopefully fast, implementations. They deliberately do not implement Java's Collection or Queue interfaces, although the API is similar.

Variants:

remove() sets the underlying array slot to null to avoid memory leaks. All other remove and poll methods call remove().

clear() discards the underlying array to avoid memory leaks. removeAll() calls clear().

Elements can be null, but this means that, if peek(), poll() or remove() return null, this could be because an element was null or because the buffer was empty. Consider using isEmpty() or size() to disambiguate.

Author:
sherstDotNet@yahoo.com

  • Field Summary

    Fields inherited from class net.sherst.util.FastRingBuffer

    capacity, count

  • Constructor Summary

    Constructors
    Constructor
    Description
    BlockingRingBuffer​(int capacity)
    Creates a new buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    add​(E e)
    Adds an element to the buffer.
    boolean
    addAll​(E[] a)
    Adds elements to the buffer, preserving their ordering in the array.
    boolean
    addAll​(Collection<E> c)
    Adds elements to the buffer, preserving their ordering in the collection.
    boolean
    at​(E o)
    Returns true if the head of the buffer (the next element that will be removed) is equal to o, compared using Objects.equals(java.lang.Object, java.lang.Object).
    boolean
    at​(E[] a)
    Returns true if the elements at the head of the buffer (the next elements that will be removed) are equal to the contents of a, compared using Objects.equals(java.lang.Object, java.lang.Object).
    boolean
    atSkip​(E o)
    Compares the head of the buffer (the next element that will be removed) to o using Objects.equals(java.lang.Object, java.lang.Object) and removes it from the buffer if there is a match.
    boolean
    atSkip​(E[] a)
    Compares the head of the buffer (the next elements that will be removed) to a using Objects.equals(java.lang.Object, java.lang.Object) and removes them from the buffer if there is a match.
    void
    clear()
    Empties the buffer.
    int
    getCapacity()
    Returns the maximum capacity of this buffer.
    boolean
    isEmpty()
    Returns true if the buffer is empty.
    boolean
    offer​(E e)
    Adds an element to the buffer if there is space for it.
    boolean
    offer​(E[] a)
    Adds elements to the buffer if there is space for them.
    boolean
    offer​(Collection<E> c)
    Adds elements to the buffer if there is space for them.
    E
    peek()
    Returns the head of the buffer (the next element that will be removed) without actually removing it.
    E
    peek​(int n)
    Returns the nth element that will be removed from the buffer, counting from 0 (peek(0) returns the first element that will be removed), or null if the buffer does not contain that many elements.
    E
    poll()
    Removes and returns the element at the head of the buffer, or null if the buffer is empty.
    E[]
    poll​(int n, Class<E> cls)
    Removes and returns n consecutive elements from the head of the buffer in the order they were added, or null if the buffer does not contain n elements.
    E
    remove()
    Removes and returns the element at the head of the buffer, or null if the buffer is empty.
    E[]
    remove​(int n, Class<E> cls)
    Removes and returns up to n consecutive elements from the head of the buffer in the order they were added.
    boolean
    removeAll()
    Empties the buffer.
    int
    size()
    Returns the number of elements in the buffer.
    int
    skip​(int n)
    Removes n elements from the head of the buffer (and discards them).

    Methods inherited from class net.sherst.util.FastRingBuffer

    contains, toList

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • BlockingRingBuffer

      public BlockingRingBuffer​(int capacity)
      Creates a new buffer.
      Parameters:
      capacity - Maximum capacity of the buffer

  • Method Details

    • add

      public boolean add​(E e)
      Adds an element to the buffer. Blocks while the buffer is full.
      Overrides:
      add in class SafeRingBuffer<E>
      Parameters:
      e - the element to add
      Returns:
      true

    • addAll

      public boolean addAll​(E[] a)
      Adds elements to the buffer, preserving their ordering in the array. Blocks until there is enough room in the buffer to add all the elements in one go.
      Overrides:
      addAll in class SafeRingBuffer<E>
      Parameters:
      a - the elements to add
      Returns:
      true

    • addAll

      public boolean addAll​(Collection<E> c)
      Adds elements to the buffer, preserving their ordering in the collection. Blocks until there is enough room in the buffer to add all the elements in one go.
      Overrides:
      addAll in class SafeRingBuffer<E>
      Parameters:
      ecol - the elements to add
      Returns:
      true

    • at

      public boolean at​(E o)
      Returns true if the head of the buffer (the next element that will be removed) is equal to o, compared using Objects.equals(java.lang.Object, java.lang.Object).
      Overrides:
      at in class SafeRingBuffer<E>
      Parameters:
      o - the value to be compared
      Returns:
      true if the head of the buffer equals o; false if the buffer is empty

    • at

      public boolean at​(E[] a)
      Returns true if the elements at the head of the buffer (the next elements that will be removed) are equal to the contents of a, compared using Objects.equals(java.lang.Object, java.lang.Object).
      Overrides:
      at in class SafeRingBuffer<E>
      Parameters:
      a - the values to be compared
      Returns:
      true if the elements at head of the buffer are equal to the elements of a; false if the buffer doesn't contain enough elements to match.

    • atSkip

      public boolean atSkip​(E o)
      Compares the head of the buffer (the next element that will be removed) to o using Objects.equals(java.lang.Object, java.lang.Object) and removes it from the buffer if there is a match.
      Overrides:
      atSkip in class SafeRingBuffer<E>
      Parameters:
      o - the value to be compared
      Returns:
      true if the head of the buffer equals o and is removed; false if the buffer is empty

    • atSkip

      public boolean atSkip​(E[] a)
      Compares the head of the buffer (the next elements that will be removed) to a using Objects.equals(java.lang.Object, java.lang.Object) and removes them from the buffer if there is a match.
      Overrides:
      atSkip in class SafeRingBuffer<E>
      Parameters:
      a - the values to be compared
      Returns:
      true if the elements at head of the buffer are equal to the elements of a; false if the buffer doesn't contain enough elements to match.

    • clear

      public void clear()
      Empties the buffer.
      Overrides:
      clear in class SafeRingBuffer<E>

    • getCapacity

      public int getCapacity()
      Returns the maximum capacity of this buffer.
      Overrides:
      getCapacity in class SafeRingBuffer<E>
      Returns:
      the maximum capacity of this buffer

    • isEmpty

      public boolean isEmpty()
      Returns true if the buffer is empty.
      Overrides:
      isEmpty in class SafeRingBuffer<E>
      Returns:
      true if the buffer is empty

    • offer

      public boolean offer​(E e)
      Adds an element to the buffer if there is space for it. Does not block.
      Overrides:
      offer in class SafeRingBuffer<E>
      Parameters:
      e - the element to add.
      Returns:
      true if there was space in the buffer and the element was added

    • offer

      public boolean offer​(E[] a)
      Adds elements to the buffer if there is space for them. Does not block.
      Overrides:
      offer in class SafeRingBuffer<E>
      Parameters:
      e - the element to add.
      Returns:
      true if there was space in the buffer and the elements were added

    • offer

      public boolean offer​(Collection<E> c)
      Adds elements to the buffer if there is space for them. Does not block.
      Overrides:
      offer in class SafeRingBuffer<E>
      Parameters:
      e - the element to add.
      Returns:
      true if there was space in the buffer and the elements were added

    • peek

      public E peek()
      Returns the head of the buffer (the next element that will be removed) without actually removing it.
      Overrides:
      peek in class SafeRingBuffer<E>
      Returns:
      the element at the head of the buffer or null if the buffer is empty

    • peek

      public E peek​(int n)
      Returns the nth element that will be removed from the buffer, counting from 0 (peek(0) returns the first element that will be removed), or null if the buffer does not contain that many elements.
      Overrides:
      peek in class SafeRingBuffer<E>
      Parameters:
      n -
      Returns:
      the nth element that will be removed from the buffer or null if the buffer does not contain that many elements

    • poll

      public E poll()
      Removes and returns the element at the head of the buffer, or null if the buffer is empty.
      Overrides:
      poll in class SafeRingBuffer<E>
      Returns:
      the element that was at the head of the buffer which was removed, or null if the buffer is empty

    • poll

      public E[] poll​(int n, Class<E> cls)
      Removes and returns n consecutive elements from the head of the buffer in the order they were added, or null if the buffer does not contain n elements.
      Overrides:
      poll in class SafeRingBuffer<E>
      Parameters:
      n - the number of elements to remove
      cls - the Class of the elements in the buffer (needed to create the array)
      Returns:
      the elements that were at the head of the buffer which were removed, or null if the buffer does not contain n elements

    • remove

      public E remove()
      Removes and returns the element at the head of the buffer, or null if the buffer is empty. Blocks while the buffer is empty.
      Overrides:
      remove in class SafeRingBuffer<E>
      Returns:
      the element that was at the head of the buffer which was removed, or null if the buffer is empty

    • remove

      public E[] remove​(int n, Class<E> cls)
      Removes and returns up to n consecutive elements from the head of the buffer in the order they were added. Blocks while the buffer does not contain enough elements.
      Overrides:
      remove in class SafeRingBuffer<E>
      Parameters:
      n - the number of elements to remove
      cls - the Class of the elements in the buffer (needed to create the array)
      Returns:
      the elements that were at the head of the buffer which were removed; the length of the array reflects the number of elements that were available

    • removeAll

      public boolean removeAll()
      Empties the buffer.
      Overrides:
      removeAll in class SafeRingBuffer<E>
      Returns:
      true

    • size

      public int size()
      Returns the number of elements in the buffer.
      Overrides:
      size in class SafeRingBuffer<E>
      Returns:
      the number of elements in the buffer

    • skip

      public int skip​(int n)
      Removes n elements from the head of the buffer (and discards them). If n>size(), only size() elements are removed. Does not block if the buffer is empty. Inspired by and named after similar methods in InputStreams and Readers.
      Overrides:
      skip in class SafeRingBuffer<E>
      Parameters:
      n - the number of elements to remove
      Returns:
      the number of elements actually removed