Package com.jogamp.common.util

Class SyncedRingbuffer<T>

java.lang.Object
com.jogamp.common.util.SyncedRingbuffer<T>
All Implemented Interfaces:
Ringbuffer<T>
public class SyncedRingbuffer<T> extends Object implements Ringbuffer<T>
Simple synchronized implementation of Ringbuffer.

All methods utilize global synchronization.

Characteristics:

  • Read position points to the next read element.
  • Write position points to the next write element.
EmptywritePos == readPossize == 0
FullwritePos == readPossize == capacity

  • Constructor Summary

    Constructors
    Constructor
    Description
    SyncedRingbuffer(Class<? extends T[]> arrayType, int capacity)
    Create an empty ring buffer instance w/ the given net capacity.
    SyncedRingbuffer(T[] copyFrom)
    Create a full ring buffer instance w/ the given array's net capacity and content.

  • Method Summary

    Modifier and Type
    Method
    Description
    final int
    capacity()
    Returns the net capacity of this ring buffer.
    final void
    clear()
    Resets the read and write position according to an empty ring buffer and set all ring buffer slots to null.
    final void
    dump(PrintStream stream, String prefix)
    Debug functionality - Dumps the contents of the internal array.
    final T
    get()
    Dequeues the oldest enqueued element if available, otherwise null.
    final T
    getBlocking()
    Dequeues the oldest enqueued element.
    final int
    getFreeSlots()
    Returns the number of free slots available to put.
    final void
    growEmptyBuffer(T[] newElements)
    Grows an empty ring buffer, increasing it's capacity about the amount.
    final void
    growFullBuffer(int growAmount)
    Grows a full ring buffer, increasing it's capacity about the amount.
    final boolean
    isEmpty()
    Returns true if this ring buffer is empty, otherwise false.
    final boolean
    isFull()
    Returns true if this ring buffer is full, otherwise false.
    final T
    peek()
    Peeks the next element at the read position w/o modifying pointer, nor blocking.
    final T
    peekBlocking()
    Peeks the next element at the read position w/o modifying pointer, but w/ blocking.
    final boolean
    put(T e)
    Enqueues the given element.
    final void
    putBlocking(T e)
    Enqueues the given element.
    final boolean
    putSame(boolean blocking)
    Enqueues the same element at it's write position, if not full.
    final void
    resetFull(T[] copyFrom)
    Resets the read and write position according to a full ring buffer and fill all slots w/ elements of array copyFrom.
    final int
    size()
    Returns the number of elements in this ring buffer.
    final String
    toString()
    Returns a short string representation incl.
    final void
    waitForFreeSlots(int count)
    Blocks until at least count free slots become available.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • SyncedRingbuffer

      public SyncedRingbuffer(T[] copyFrom) throws IllegalArgumentException
      Create a full ring buffer instance w/ the given array's net capacity and content.

      Example for a 10 element Integer array: 

        Integer[] source = new Integer[10];
  // fill source with content ..
  Ringbuffer rb = new SyncedRingbuffer(source);

      isFull() returns true on the newly created full ring buffer.

      Implementation will allocate an internal array with size of array copyFrom and copy all elements from array copyFrom into the internal array.

      Parameters:
      copyFrom - mandatory source array determining ring buffer's net capacity() and initial content.
      Throws:
      IllegalArgumentException - if copyFrom is null

    • SyncedRingbuffer

      public SyncedRingbuffer(Class<? extends T[]> arrayType, int capacity)
      Create an empty ring buffer instance w/ the given net capacity.

      Example for a 10 element Integer array: 

        Ringbuffer rb = new SyncedRingbuffer(10, Integer[].class);

      isEmpty() returns true on the newly created empty ring buffer.

      Implementation will allocate an internal array of size capacity.

      Parameters:
      arrayType - the array type of the created empty internal array.
      capacity - the initial net capacity of the ring buffer

  • Method Details

    • toString

      public final String toString()
      Description copied from interface: Ringbuffer
      Returns a short string representation incl. size/capacity and internal r/w index (impl. dependent).
      Specified by:
      toString in interface Ringbuffer<T>
      Overrides:
      toString in class Object

    • dump

      public final void dump(PrintStream stream, String prefix)
      Description copied from interface: Ringbuffer
      Debug functionality - Dumps the contents of the internal array.
      Specified by:
      dump in interface Ringbuffer<T>

    • capacity

      public final int capacity()
      Description copied from interface: Ringbuffer
      Returns the net capacity of this ring buffer.
      Specified by:
      capacity in interface Ringbuffer<T>

    • clear

      public final void clear()
      Resets the read and write position according to an empty ring buffer and set all ring buffer slots to null.

      Ringbuffer.isEmpty() will return true after calling this method.

      Implementation sets read and write position to zero.

      Specified by:
      clear in interface Ringbuffer<T>

    • resetFull

      public final void resetFull(T[] copyFrom) throws IllegalArgumentException
      Description copied from interface: Ringbuffer
      Resets the read and write position according to a full ring buffer and fill all slots w/ elements of array copyFrom.

      Array's copyFrom elements will be copied into the internal array, hence it's length must be equal to Ringbuffer.capacity().

      Specified by:
      resetFull in interface Ringbuffer<T>
      Parameters:
      copyFrom - Mandatory array w/ length Ringbuffer.capacity() to be copied into the internal array.
      Throws:
      IllegalArgumentException - if copyFrom is null.

    • size

      public final int size()
      Description copied from interface: Ringbuffer
      Returns the number of elements in this ring buffer.
      Specified by:
      size in interface Ringbuffer<T>

    • getFreeSlots

      public final int getFreeSlots()
      Description copied from interface: Ringbuffer
      Returns the number of free slots available to put.
      Specified by:
      getFreeSlots in interface Ringbuffer<T>

    • isEmpty

      public final boolean isEmpty()
      Description copied from interface: Ringbuffer
      Returns true if this ring buffer is empty, otherwise false.
      Specified by:
      isEmpty in interface Ringbuffer<T>

    • isFull

      public final boolean isFull()
      Description copied from interface: Ringbuffer
      Returns true if this ring buffer is full, otherwise false.
      Specified by:
      isFull in interface Ringbuffer<T>

    • get

      public final T get()
      Dequeues the oldest enqueued element if available, otherwise null.

      The returned ring buffer slot will be set to null to release the reference and move ownership to the caller.

      Method is non blocking and returns immediately;.

      Implementation returns the element at the current read position and advances it, if not empty.

      Specified by:
      get in interface Ringbuffer<T>
      Returns:
      the oldest put element if available, otherwise null.

    • getBlocking

      public final T getBlocking() throws InterruptedException
      Dequeues the oldest enqueued element.

      The returned ring buffer slot will be set to null to release the reference and move ownership to the caller.

      Methods blocks until an element becomes available via put.

      Implementation returns the element at the current read position and advances it, if not empty.

      Specified by:
      getBlocking in interface Ringbuffer<T>
      Returns:
      the oldest put element
      Throws:
      InterruptedException

    • peek

      public final T peek()
      Description copied from interface: Ringbuffer
      Peeks the next element at the read position w/o modifying pointer, nor blocking.
      Specified by:
      peek in interface Ringbuffer<T>
      Returns:
      null if empty, otherwise the element which would be read next.

    • peekBlocking

      public final T peekBlocking() throws InterruptedException
      Description copied from interface: Ringbuffer
      Peeks the next element at the read position w/o modifying pointer, but w/ blocking.
      Specified by:
      peekBlocking in interface Ringbuffer<T>
      Returns:
      null if empty, otherwise the element which would be read next.
      Throws:
      InterruptedException

    • put

      public final boolean put(T e)
      Enqueues the given element.

      Returns true if successful, otherwise false in case buffer is full.

      Method is non blocking and returns immediately;.

      Implementation stores the element at the current write position and advances it, if not full.

      Specified by:
      put in interface Ringbuffer<T>

    • putBlocking

      public final void putBlocking(T e) throws InterruptedException
      Enqueues the given element.

      Method blocks until a free slot becomes available via get.

      Implementation stores the element at the current write position and advances it, if not full.

      Specified by:
      putBlocking in interface Ringbuffer<T>
      Throws:
      InterruptedException

    • putSame

      public final boolean putSame(boolean blocking) throws InterruptedException
      Enqueues the same element at it's write position, if not full.

      Returns true if successful, otherwise false in case buffer is full.

      If blocking is true, method blocks until a free slot becomes available via get.

      Implementation keeps the element at the current write position and advances it, if not full.

      Specified by:
      putSame in interface Ringbuffer<T>
      Parameters:
      blocking - if true, wait until a free slot becomes available via get.
      Throws:
      InterruptedException

    • waitForFreeSlots

      public final void waitForFreeSlots(int count) throws InterruptedException
      Description copied from interface: Ringbuffer
      Blocks until at least count free slots become available.
      Specified by:
      waitForFreeSlots in interface Ringbuffer<T>
      Throws:
      InterruptedException

    • growEmptyBuffer

      public final void growEmptyBuffer(T[] newElements) throws IllegalStateException, IllegalArgumentException
      Description copied from interface: Ringbuffer
      Grows an empty ring buffer, increasing it's capacity about the amount.

      Growing an empty ring buffer increases it's size about the amount, i.e. renders it not empty. The new elements are inserted at the read position, able to be read out via Ringbuffer.get() etc.

      Specified by:
      growEmptyBuffer in interface Ringbuffer<T>
      Parameters:
      newElements - array of new full elements the empty buffer shall grow about.
      Throws:
      IllegalStateException - if buffer is not empty
      IllegalArgumentException - if newElements is null

    • growFullBuffer

      public final void growFullBuffer(int growAmount) throws IllegalStateException, IllegalArgumentException
      Description copied from interface: Ringbuffer
      Grows a full ring buffer, increasing it's capacity about the amount.

      Growing a full ring buffer leaves the size intact, i.e. renders it not full. New null elements are inserted at the write position, able to be written to via Ringbuffer.put(Object) etc.

      Specified by:
      growFullBuffer in interface Ringbuffer<T>
      Parameters:
      growAmount - the amount of elements the buffer shall grow about
      Throws:
      IllegalStateException - if buffer is not full
      IllegalArgumentException - if amount is < 0