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

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.
T[]	getInternalArray() Deprecated. This method should not be required
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.

getInternalArray

T[] getInternalArray()

Deprecated. This method should not be required

Returns the internal array as-is, i.e. w/o a copy.

The layout and size of the internal array is implementation dependent.

Users shall not modify or rely on the returned 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