Package org.evoludo.util
Class RingBuffer<T>
Object
RingBuffer<T>
- Type Parameters:
T
- data type of buffer
- All Implemented Interfaces:
Iterable<T>
Non-blocking ring buffer. Entries can be added continuously but only the most
recent entries are retained up to the buffers capacity. This is useful to
retain, for example, the most recent entries of a time series.
Note: arrays, primitives and java generics don't play well together, which necessitates specialized instances of RingBuffer. In particular, subclasses don't work either, which results in code redundancy in the different implementations.
- Author:
- Christoph Hauert
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate class
Iterates backwards over all elements in this buffer starting with the most recent entry.private class
Iterates forward over all elements in this buffer starting with the oldest entry.private class
Iterates forward over all elements in this buffer starting with the oldest entry. -
Field Summary
FieldsModifier and TypeFieldDescriptionArray to hold buffer ofT
objects.(package private) int
Buffer capacity, i.e.(package private) int
The depth of a buffer containing arrays.(package private) int
Index of most recently added element in buffer. -
Constructor Summary
ConstructorsConstructorDescriptionRingBuffer
(int capacity) Create new ring buffer for storing up tocapacity
entries. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Append newentry
to ring buffer.protected int
arrayLength
(T entry) Helper method to deal withentry
representing an array.void
clear()
Remove all entries from ring buffer.first()
Return first/oldest buffer entry.get
(int index) Retrieve buffer entry at positionindex
(without removing it).int
Get the capacity of the ring buffer.int
getDepth()
Get the depth of array entries.int
getSize()
Get the number of entries in the ring buffer.boolean
isEmpty()
Check if the ring buffer is empty.boolean
isFull()
Check if the ring buffer is at capacity.iterator()
last()
Return last/most recent buffer entry.Returns a list iterator over all elements in this buffer in chronological order.listIterator
(int index) Returns a list iterator over all elements in this buffer in chronological order starting with entry atindex
.ordered()
Returns an iterator over all elements in this buffer in chronological order.Replace buffer entry at positionindex
withentry
.Replace most recent entry in ring buffer withentry
.void
setCapacity
(int capacity) Set maximum number of entries in ring buffer tocapacity
.Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface Iterable
forEach, spliterator
-
Field Details
-
buffer
Array to hold buffer ofT
objects. -
bufferPtr
int bufferPtrIndex of most recently added element in buffer. -
bufferCapacity
int bufferCapacityBuffer capacity, i.e. the maximum number of elements the buffer can contain. -
bufferDepth
int bufferDepthThe depth of a buffer containing arrays.>0
: length of array entries0
: entries are objects (not arrays)-1
: entries are arrays of different lengths-2
: buffer is mixture of objects and arrays
-
-
Constructor Details
-
RingBuffer
Create new ring buffer for storing up tocapacity
entries.- Parameters:
capacity
- maximum number of entries- Throws:
IllegalArgumentException
- ifcapacity≤0
-
-
Method Details
-
setCapacity
Set maximum number of entries in ring buffer tocapacity
. If the current buffersize
exceeds the newcapacity
then entries with indicescapacity
throughsize-1
are discarded. After setting the capacity the size of the buffer is at mostcapacity
.- Parameters:
capacity
- maximum number of entries- Throws:
IllegalArgumentException
- ifcapacity≤0
-
getCapacity
public int getCapacity()Get the capacity of the ring buffer. The capacity is the maximum number of entries the buffer can hold.- Returns:
- the capacity of the ring buffer
-
getDepth
public int getDepth()Get the depth of array entries.- Returns:
>0
: length of array entries0
: entries are objects (not arrays)-1
: entries are arrays of different lengths-2
: buffer is mixture of objects and arrays
-
getSize
public int getSize()Get the number of entries in the ring buffer.- Returns:
- the number of entries
-
isEmpty
public boolean isEmpty()Check if the ring buffer is empty.- Returns:
true
if ring buffer is empty
-
isFull
public boolean isFull()Check if the ring buffer is at capacity.- Returns:
true
if ring buffer is at capacity
-
clear
public void clear()Remove all entries from ring buffer. Reset buffer size to zero. -
append
Append newentry
to ring buffer. If buffer is at capacity, the oldest entry is removed.Important:
Must create copy of data/array for adding to buffer. Otherwise, any subsequent changes to the data will also change the buffer. Copying of the entry cannot be reliably done in RingBuffer without reflection or other trickery.- Parameters:
entry
- to add to buffer- See Also:
-
arrayLength
Helper method to deal withentry
representing an array. Returns the length of the array or-1
if it is not an array.- Parameters:
entry
- the buffer entry- Returns:
- the length of the array or
-1
ifentry
is not an array - Throws:
IllegalArgumentException
- if unable to determine array type ofentry
-
get
Retrieve buffer entry at positionindex
(without removing it). The most recently added entry has index 0, the one before index 1, etc. up the buffer size-1 (or its capacity-1, if the buffer is at capacity).- Parameters:
index
- of entry to retrieve- Returns:
- buffer entry
- Throws:
IllegalArgumentException
- ifindex<0
orindex>size-1
.
-
first
Return first/oldest buffer entry.- Returns:
- first buffer entry or
null
if buffer is empty
-
last
Return last/most recent buffer entry.- Returns:
- first buffer entry or
null
if buffer is empty
-
replace
Replace buffer entry at positionindex
withentry
. Return old entry at positionindex
. The most recently added entry has index 0, the one before index 1, etc. up the buffer size-1 (or its capacity-1, if the buffer is at capacity).Important:
Must create copy of data/array for including in buffer. Otherwise, any subsequent changes to the data will also change the buffer. Copying of the entry cannot be reliably done in RingBuffer without reflection or other trickery.- Parameters:
index
- of entry to replaceentry
- replacement- Returns:
- previous buffer entry
- Throws:
IllegalArgumentException
- ifindex<0
orindex>size-1
.- See Also:
-
replace
Replace most recent entry in ring buffer withentry
.Important:
Must create copy of data/array for including in buffer. Otherwise, any subsequent changes to the data will also change the buffer. Copying of the entry cannot be reliably done in RingBuffer without reflection or other trickery.- Parameters:
entry
- replacement- Returns:
- previous buffer entry
- See Also:
-
iterator
-
ordered
Returns an iterator over all elements in this buffer in chronological order.- Returns:
- the forward iterator
-
listIterator
Returns a list iterator over all elements in this buffer in chronological order.- Returns:
- the forward list iterator
-
listIterator
Returns a list iterator over all elements in this buffer in chronological order starting with entry atindex
.- Parameters:
index
- the index of the first element to be returned- Returns:
- the forward list iterator
-