Package 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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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;.

      • 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

      • 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