Class LFRingbuffer<T>
- 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 ofRingbuffer, exposing lock-freeget*(..)andput*(..)methods.Implementation utilizes the Always Keep One Slot Open, hence implementation maintains an internal array of
capacityplus one!Implementation is thread safe if:
get*(..)operations are performed from one thread only.put*(..)operations are performed from one thread only.get*(..)andput*(..)thread may be the same.
Following methods utilize global synchronization:
User needs to synchronize above methods w/ the lock-free w/get*(..)andput*(..)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 Description LFRingbuffer(Class<? extends T[]> arrayType, int capacity)Create an empty ring buffer instance w/ the given netcapacity.LFRingbuffer(T[] copyFrom)Create a full ring buffer instance w/ the given array's net capacity and content.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description intcapacity()Returns the net capacity of this ring buffer.voidclear()Resets the read and write position according to an empty ring buffer and set all ring buffer slots tonull.voiddump(PrintStream stream, String prefix)Debug functionality - Dumps the contents of the internal array.Tget()Dequeues the oldest enqueued element if available, otherwise null.TgetBlocking()Dequeues the oldest enqueued element.intgetFreeSlots()Returns the number of free slots available to put.voidgrowEmptyBuffer(T[] newElements)Grows an empty ring buffer, increasing it's capacity about the amount.voidgrowFullBuffer(int growAmount)Grows a full ring buffer, increasing it's capacity about the amount.booleanisEmpty()Returns true if this ring buffer is empty, otherwise false.booleanisFull()Returns true if this ring buffer is full, otherwise false.Tpeek()Peeks the next element at the read position w/o modifying pointer, nor blocking.TpeekBlocking()Peeks the next element at the read position w/o modifying pointer, but w/ blocking.booleanput(T e)Enqueues the given element.voidputBlocking(T e)Enqueues the given element.booleanputSame(boolean blocking)Enqueues the same element at it's write position, if not full.voidresetFull(T[] copyFrom)Resets the read and write position according to a full ring buffer and fill all slots w/ elements of arraycopyFrom.intsize()Returns the number of elements in this ring buffer.StringtoString()Returns a short string representation incl.voidwaitForFreeSlots(int count)Blocks until at leastcountfree slots become available.
-
-
-
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
copyFromplus one, and copy all elements from arraycopyFrominto the internal array.- Parameters:
copyFrom- mandatory source array determining ring buffer's netcapacity()and initial content.- Throws:
IllegalArgumentException- ifcopyFromisnull
-
LFRingbuffer
public LFRingbuffer(Class<? extends T[]> arrayType, int capacity)
Create an empty ring buffer instance w/ the given netcapacity.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
capacityplus 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:RingbufferReturns a short string representation incl. size/capacity and internal r/w index (impl. dependent).- Specified by:
toStringin interfaceRingbuffer<T>- Overrides:
toStringin classObject
-
dump
public final void dump(PrintStream stream, String prefix)
Description copied from interface:RingbufferDebug functionality - Dumps the contents of the internal array.- Specified by:
dumpin interfaceRingbuffer<T>
-
capacity
public final int capacity()
Description copied from interface:RingbufferReturns the net capacity of this ring buffer.- Specified by:
capacityin interfaceRingbuffer<T>
-
clear
public final void clear()
Description copied from interface:RingbufferResets the read and write position according to an empty ring buffer and set all ring buffer slots tonull.Ringbuffer.isEmpty()will returntrueafter calling this method.- Specified by:
clearin interfaceRingbuffer<T>
-
resetFull
public final void resetFull(T[] copyFrom) throws IllegalArgumentException
Description copied from interface:RingbufferResets the read and write position according to a full ring buffer and fill all slots w/ elements of arraycopyFrom.Array's
copyFromelements will be copied into the internal array, hence it's length must be equal toRingbuffer.capacity().- Specified by:
resetFullin interfaceRingbuffer<T>- Parameters:
copyFrom- Mandatory array w/ lengthRingbuffer.capacity()to be copied into the internal array.- Throws:
IllegalArgumentException- ifcopyFromisnull.
-
size
public final int size()
Description copied from interface:RingbufferReturns the number of elements in this ring buffer.- Specified by:
sizein interfaceRingbuffer<T>
-
getFreeSlots
public final int getFreeSlots()
Description copied from interface:RingbufferReturns the number of free slots available to put.- Specified by:
getFreeSlotsin interfaceRingbuffer<T>
-
isEmpty
public final boolean isEmpty()
Description copied from interface:RingbufferReturns true if this ring buffer is empty, otherwise false.- Specified by:
isEmptyin interfaceRingbuffer<T>
-
isFull
public final boolean isFull()
Description copied from interface:RingbufferReturns true if this ring buffer is full, otherwise false.- Specified by:
isFullin interfaceRingbuffer<T>
-
get
public final T get()
Dequeues the oldest enqueued element if available, otherwise null.The returned ring buffer slot will be set to
nullto 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:
getin interfaceRingbuffer<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
nullto 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:
getBlockingin interfaceRingbuffer<T>- Returns:
- the oldest put element
- Throws:
InterruptedException
-
peek
public final T peek()
Description copied from interface:RingbufferPeeks the next element at the read position w/o modifying pointer, nor blocking.- Specified by:
peekin interfaceRingbuffer<T>- Returns:
nullif empty, otherwise the element which would be read next.
-
peekBlocking
public final T peekBlocking() throws InterruptedException
Description copied from interface:RingbufferPeeks the next element at the read position w/o modifying pointer, but w/ blocking.- Specified by:
peekBlockingin interfaceRingbuffer<T>- Returns:
nullif 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:
putin interfaceRingbuffer<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:
putBlockingin interfaceRingbuffer<T>- Throws:
InterruptedException
-
putSame
public final boolean putSame(boolean blocking) throws InterruptedExceptionEnqueues the same element at it's write position, if not full.Returns true if successful, otherwise false in case buffer is full.
If
blockingis 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:
putSamein interfaceRingbuffer<T>- Parameters:
blocking- if true, wait until a free slot becomes available via get.- Throws:
InterruptedException
-
waitForFreeSlots
public final void waitForFreeSlots(int count) throws InterruptedExceptionDescription copied from interface:RingbufferBlocks until at leastcountfree slots become available.- Specified by:
waitForFreeSlotsin interfaceRingbuffer<T>- Throws:
InterruptedException
-
growEmptyBuffer
public final void growEmptyBuffer(T[] newElements) throws IllegalStateException, IllegalArgumentException
Description copied from interface:RingbufferGrows 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:
growEmptyBufferin interfaceRingbuffer<T>- Parameters:
newElements- array of new full elements the empty buffer shall grow about.- Throws:
IllegalStateException- if buffer is not emptyIllegalArgumentException- if newElements is null
-
growFullBuffer
public final void growFullBuffer(int growAmount) throws IllegalStateException, IllegalArgumentExceptionDescription copied from interface:RingbufferGrows 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
nullelements are inserted at the write position, able to be written to viaRingbuffer.put(Object)etc.- Specified by:
growFullBufferin interfaceRingbuffer<T>- Parameters:
growAmount- the amount of elements the buffer shall grow about- Throws:
IllegalStateException- if buffer is not fullIllegalArgumentException- if amount is < 0
-
-