LFRingbuffer (GlueGen Runtime Documentation)

java.lang.Object
- com.jogamp.common.util.LFRingbuffer<T>

All Implemented Interfaces:

Ringbuffer<T>
```
public class LFRingbuffer<T>
extends Object
implements Ringbuffer<T>
```
Simple implementation of Ringbuffer, exposing lock-free get*(..) and put*(..) methods.
Implementation utilizes the Always Keep One Slot Open, hence implementation maintains an internal array of capacity plus one!

Implementation is thread safe if:
- get*(..) operations are performed from one thread only.
- put*(..) operations are performed from one thread only.
- get*(..) and put*(..) thread may be the same.
Following methods utilize global synchronization:
User needs to synchronize above methods w/ the lock-free w/ get*(..) and put*(..) methods, e.g. by controlling their threads before invoking the above.

Characteristics:
- Read position points to the last read element.
- Write position points to the last written element.
Empty writePos == readPos size == 0

Full writePos == readPos - 1 size == capacity

Constructor Summary

Constructors
Constructor and Description
`LFRingbuffer(Class<? extends T[]> arrayType, int capacity)` Create an empty ring buffer instance w/ the given net `capacity`.
`LFRingbuffer(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
  - LFRingbuffer
```
public LFRingbuffer(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 LFRingbuffer(source);
 
```
    isFull() returns true on the newly created full ring buffer.
    
    Implementation will allocate an internal array with size of array copyFrom plus one, 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
  - LFRingbuffer
```
public LFRingbuffer(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 LFRingbuffer(10, Integer[].class);
 
```
    isEmpty() returns true on the newly created empty ring buffer.
    
    Implementation will allocate an internal array of size capacity plus one.
    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()
```
    Description copied from interface: Ringbuffer
    
    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.
    
    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 advances the read position and returns the element at 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 advances the read position and returns the element at 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 advances the write position and stores the given element at 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 advances the write position and stores the given element at 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 advances the write position and keeps the element at 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

Empty	writePos == readPos	size == 0
Full	writePos == readPos - 1	size == capacity

Class LFRingbuffer<T>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LFRingbuffer

LFRingbuffer

Method Detail

toString

dump

capacity

clear

resetFull

size

getFreeSlots

isEmpty

isFull

get

getBlocking

peek

peekBlocking

put

putBlocking

putSame

waitForFreeSlots

growEmptyBuffer

growFullBuffer