com.jogamp.common.util

## Interface Ringbuffer<T>

- All Known Implementing Classes:
    LFRingbuffer, SyncedRingbuffer

      public interface Ringbuffer<T>

  Ring buffer interface, a.k.a circular buffer.

  Caller can chose whether to block until get / put is able to proceed or not.

  Caller can chose whether to pass an empty array and clear references at get, or using a preset array for circular access of same objects.

  Synchronization and hence thread safety details belong to the implementation.

- - ### 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 amount)` 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.

- - ### Method Detail

    - #### toString

          String toString()

      Returns a short string representation incl. size/capacity and internal r/w index (impl. dependent).
      Overrides:
        `toString` in class `Object`

    - #### dump

          void dump(PrintStream stream,
                  String prefix)

      Debug functionality - Dumps the contents of the internal array.

    - #### capacity

          int capacity()

      Returns the net capacity of this ring buffer.

    - #### clear

          void clear()

      Resets the read and write position according to an empty ring buffer and set all ring buffer slots to `null`.

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

    - #### resetFull

          void resetFull(T[] copyFrom)
                         throws IllegalArgumentException

      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 `capacity()`.

      Parameters:
        `copyFrom` - Mandatory array w/ length `capacity()` to be copied into the internal array.
      Throws:
        `IllegalArgumentException` - if `copyFrom` is `null`.
        `IllegalArgumentException` - if `copyFrom`'s length is different from `capacity()`.

    - #### size

          int size()

      Returns the number of elements in this ring buffer.

    - #### getFreeSlots

          int getFreeSlots()

      Returns the number of free slots available to put.

    - #### isEmpty

          boolean isEmpty()

      Returns true if this ring buffer is empty, otherwise false.

    - #### isFull

          boolean isFull()

      Returns true if this ring buffer is full, otherwise false.

    - #### get

          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;.

      Returns:
        the oldest put element if available, otherwise null.

    - #### getBlocking

          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.

      Returns:
        the oldest put element
      Throws:
        `InterruptedException`

    - #### peek

          T peek()

      Peeks the next element at the read position w/o modifying pointer, nor blocking.
      Returns:
        `null` if empty, otherwise the element which would be read next.

    - #### peekBlocking

          T peekBlocking()
                         throws InterruptedException

      Peeks the next element at the read position w/o modifying pointer, but w/ blocking.
      Returns:
        `null` if empty, otherwise the element which would be read next.
      Throws:
        `InterruptedException`

    - #### put

          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;.

    - #### putBlocking

          void putBlocking(T e)
                           throws InterruptedException

      Enqueues the given element.

      Method blocks until a free slot becomes available via get.

      Throws:
        `InterruptedException`

    - #### putSame

          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.

      Parameters:
        `blocking` - if true, wait until a free slot becomes available via get.
      Throws:
        `InterruptedException`

    - #### waitForFreeSlots

          void waitForFreeSlots(int count)
                                throws InterruptedException

      Blocks until at least `count` free slots become available.
      Throws:
        `InterruptedException`

    - #### growEmptyBuffer

          void growEmptyBuffer(T[] newElements)
                               throws IllegalStateException,
                                      IllegalArgumentException

      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 `get()` etc.

      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

          void growFullBuffer(int amount)
                              throws IllegalStateException,
                                     IllegalArgumentException

      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 `put(Object)` etc.

      Parameters:
        `amount` - the amount of elements the buffer shall grow about
      Throws:
        `IllegalStateException` - if buffer is not full
        `IllegalArgumentException` - if amount is < 0