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.

  Empty | writePos == readPos | size == 0
  Full | writePos == readPos | size == capacity

- - ### Constructor Summary

    Constructors
    Constructor and 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

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

    - #### 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 Detail

    - #### 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