jaulib v1.3.0
Jau Support Library (C++, Java, ..)
Ringbuffer.java
Go to the documentation of this file.
1/**
2 * Author: Sven Gothel <sgothel@jausoft.com>
3 * Copyright (c) 2020 Gothel Software e.K.
4 * Copyright (c) 2013 Gothel Software e.K.
5 * Copyright (c) 2013 JogAmp Community.
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining
8 * a copy of this software and associated documentation files (the
9 * "Software"), to deal in the Software without restriction, including
10 * without limitation the rights to use, copy, modify, merge, publish,
11 * distribute, sublicense, and/or sell copies of the Software, and to
12 * permit persons to whom the Software is furnished to do so, subject to
13 * the following conditions:
14 *
15 * The above copyright notice and this permission notice shall be
16 * included in all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
22 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
23 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
24 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25 */
26package org.jau.util;
27
28import java.io.PrintStream;
29
30/**
31 * Ring buffer interface, a.k.a circular buffer.
32 * <p>
33 * Caller can chose whether to block until get / put is able to proceed or not.
34 * </p>
35 * <p>
36 * Caller can chose whether to pass an empty array and clear references at get,
37 * or using a preset array for circular access of same objects.
38 * </p>
39 * <p>
40 * Synchronization and hence thread safety details belong to the implementation.
41 * </p>
42 */
43public interface Ringbuffer<T> {
44
45 /** Returns a short string representation incl. size/capacity and internal r/w index (impl. dependent). */
46 @Override
47 public String toString();
48
49 /** Debug functionality - Dumps the contents of the internal array. */
50 public void dump(PrintStream stream, String prefix);
51
52 /** Returns the net capacity of this ring buffer. */
53 public int capacity();
54
55 /**
56 * Resets the read and write position according to an empty ring buffer
57 * and set all ring buffer slots to <code>null</code>.
58 * <p>
59 * {@link #isEmpty()} will return <code>true</code> after calling this method.
60 * </p>
61 */
62 public void clear();
63
64 /**
65 * Resets the read and write position according to a full ring buffer
66 * and fill all slots w/ elements of array <code>copyFrom</code>.
67 * <p>
68 * Array's <code>copyFrom</code> elements will be copied into the internal array,
69 * hence it's length must be equal to {@link #capacity()}.
70 * </p>
71 * @param copyFrom Mandatory array w/ length {@link #capacity()} to be copied into the internal array.
72 * @throws IllegalArgumentException if <code>copyFrom</code> is <code>null</code>.
73 * @throws IllegalArgumentException if <code>copyFrom</code>'s length is different from {@link #capacity()}.
74 */
75 public void resetFull(T[] copyFrom) throws IllegalArgumentException;
76
77 /** Returns the number of elements in this ring buffer. */
78 public int size();
79
80 /** Returns the number of free slots available to put. */
81 public int getFreeSlots();
82
83 /** Returns true if this ring buffer is empty, otherwise false. */
84 public boolean isEmpty();
85
86 /** Returns true if this ring buffer is full, otherwise false. */
87 public boolean isFull();
88
89 /**
90 * Dequeues the oldest enqueued element if available, otherwise null.
91 * <p>
92 * The returned ring buffer slot will be set to <code>null</code> to release the reference
93 * and move ownership to the caller.
94 * </p>
95 * <p>
96 * Method is non blocking and returns immediately;.
97 * </p>
98 * @return the oldest put element if available, otherwise null.
99 */
100 public T get();
101
102 /**
103 * Dequeues the oldest enqueued element.
104 * <p>
105 * The returned ring buffer slot will be set to <code>null</code> to release the reference
106 * and move ownership to the caller.
107 * </p>
108 * <p>
109 * Methods blocks until an element becomes available via put.
110 * </p>
111 * @return the oldest put element
112 * @throws InterruptedException
113 */
114 public T getBlocking() throws InterruptedException;
115
116 /**
117 * Peeks the next element at the read position w/o modifying pointer, nor blocking.
118 * @return <code>null</code> if empty, otherwise the element which would be read next.
119 */
120 public T peek();
121
122 /**
123 * Peeks the next element at the read position w/o modifying pointer, but w/ blocking.
124 * @return <code>null</code> if empty, otherwise the element which would be read next.
125 */
126 public T peekBlocking() throws InterruptedException;
127
128 /**
129 * Enqueues the given element.
130 * <p>
131 * Returns true if successful, otherwise false in case buffer is full.
132 * </p>
133 * <p>
134 * Method is non blocking and returns immediately;.
135 * </p>
136 */
137 public boolean put(T e);
138
139 /**
140 * Enqueues the given element.
141 * <p>
142 * Method blocks until a free slot becomes available via get.
143 * </p>
144 * @throws InterruptedException
145 */
146 public void putBlocking(T e) throws InterruptedException;
147
148 /**
149 * Enqueues the same element at it's write position, if not full.
150 * <p>
151 * Returns true if successful, otherwise false in case buffer is full.
152 * </p>
153 * <p>
154 * If <code>blocking</code> is true, method blocks until a free slot becomes available via get.
155 * </p>
156 * @param blocking if true, wait until a free slot becomes available via get.
157 * @throws InterruptedException
158 */
159 public boolean putSame(boolean blocking) throws InterruptedException;
160
161 /**
162 * Blocks until at least <code>count</code> free slots become available.
163 * @throws InterruptedException
164 */
165 public void waitForFreeSlots(int count) throws InterruptedException;
166
167 /**
168 * Grows an empty ring buffer, increasing it's capacity about the amount.
169 * <p>
170 * Growing an empty ring buffer increases it's size about the amount, i.e. renders it not empty.
171 * The new elements are inserted at the read position, able to be read out via {@link #get()} etc.
172 * </p>
173 *
174 * @param newElements array of new full elements the empty buffer shall grow about.
175 * @throws IllegalStateException if buffer is not empty
176 * @throws IllegalArgumentException if newElements is null
177 */
178 public void growEmptyBuffer(T[] newElements) throws IllegalStateException, IllegalArgumentException;
179
180 /**
181 * Grows a full ring buffer, increasing it's capacity about the amount.
182 * <p>
183 * Growing a full ring buffer leaves the size intact, i.e. renders it not full.
184 * New <code>null</code> elements are inserted at the write position, able to be written to via {@link #put(Object)} etc.
185 * </p>
186 * @param amount the amount of elements the buffer shall grow about
187 *
188 * @throws IllegalStateException if buffer is not full
189 * @throws IllegalArgumentException if amount is < 0
190 */
191 public void growFullBuffer(int amount) throws IllegalStateException, IllegalArgumentException;
192}
Ring buffer interface, a.k.a circular buffer.
Definition: Ringbuffer.java:43
void waitForFreeSlots(int count)
Blocks until at least count free slots become available.
void putBlocking(T e)
Enqueues the given element.
int size()
Returns the number of elements in this ring buffer.
int getFreeSlots()
Returns the number of free slots available to put.
T getBlocking()
Dequeues the oldest enqueued element.
void dump(PrintStream stream, String prefix)
Debug functionality - Dumps the contents of the internal array.
boolean putSame(boolean blocking)
Enqueues the same element at it's write position, if not full.
String toString()
Returns a short string representation incl.
void resetFull(T[] copyFrom)
Resets the read and write position according to a full ring buffer and fill all slots w/ elements of ...
int capacity()
Returns the net capacity of this ring buffer.
boolean isEmpty()
Returns true if this ring buffer is empty, otherwise false.
boolean put(T e)
Enqueues the given element.
void clear()
Resets the read and write position according to an empty ring buffer and set all ring buffer slots to...
T peek()
Peeks the next element at the read position w/o modifying pointer, nor blocking.
boolean isFull()
Returns true if this ring buffer is full, otherwise false.
void growEmptyBuffer(T[] newElements)
Grows an empty ring buffer, increasing it's capacity about the amount.
T peekBlocking()
Peeks the next element at the read position w/o modifying pointer, but w/ blocking.
void growFullBuffer(int amount)
Grows a full ring buffer, increasing it's capacity about the amount.