GlueGen v2.6.0-rc-20250712
GlueGen, Native Binding Generator for Java™ (public API).
Ringbuffer.java
Go to the documentation of this file.
1/**
2 * Copyright 2013 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28package com.jogamp.common.util;
29
30import java.io.PrintStream;
31
32/**
33 * Ring buffer interface, a.k.a circular buffer.
34 * <p>
35 * Caller can chose whether to block until get / put is able to proceed or not.
36 * </p>
37 * <p>
38 * Caller can chose whether to pass an empty array and clear references at get,
39 * or using a preset array for circular access of same objects.
40 * </p>
41 * <p>
42 * Synchronization and hence thread safety details belong to the implementation.
43 * </p>
44 */
45public interface Ringbuffer<T> {
46
47 /** Returns a short string representation incl. size/capacity and internal r/w index (impl. dependent). */
48 @Override
49 public String toString();
50
51 /** Debug functionality - Dumps the contents of the internal array. */
52 public void dump(PrintStream stream, String prefix);
53
54 /** Returns the net capacity of this ring buffer. */
55 public int capacity();
56
57 /**
58 * Resets the read and write position according to an empty ring buffer
59 * and set all ring buffer slots to <code>null</code>.
60 * <p>
61 * {@link #isEmpty()} will return <code>true</code> after calling this method.
62 * </p>
63 */
64 public void clear();
65
66 /**
67 * Resets the read and write position according to a full ring buffer
68 * and fill all slots w/ elements of array <code>copyFrom</code>.
69 * <p>
70 * Array's <code>copyFrom</code> elements will be copied into the internal array,
71 * hence it's length must be equal to {@link #capacity()}.
72 * </p>
73 * @param copyFrom Mandatory array w/ length {@link #capacity()} to be copied into the internal array.
74 * @throws IllegalArgumentException if <code>copyFrom</code> is <code>null</code>.
75 * @throws IllegalArgumentException if <code>copyFrom</code>'s length is different from {@link #capacity()}.
76 */
77 public void resetFull(T[] copyFrom) throws IllegalArgumentException;
78
79 /** Returns the number of elements in this ring buffer. */
80 public int size();
81
82 /** Returns the number of free slots available to put. */
83 public int getFreeSlots();
84
85 /** Returns true if this ring buffer is empty, otherwise false. */
86 public boolean isEmpty();
87
88 /** Returns true if this ring buffer is full, otherwise false. */
89 public boolean isFull();
90
91 /**
92 * Dequeues the oldest enqueued element if available, otherwise null.
93 * <p>
94 * The returned ring buffer slot will be set to <code>null</code> to release the reference
95 * and move ownership to the caller.
96 * </p>
97 * <p>
98 * Method is non blocking and returns immediately;.
99 * </p>
100 * @return the oldest put element if available, otherwise null.
101 */
102 public T get();
103
104 /**
105 * Dequeues the oldest enqueued element.
106 * <p>
107 * The returned ring buffer slot will be set to <code>null</code> to release the reference
108 * and move ownership to the caller.
109 * </p>
110 * <p>
111 * Methods blocks until an element becomes available via put.
112 * </p>
113 * @return the oldest put element
114 * @throws InterruptedException
115 */
116 public T getBlocking() throws InterruptedException;
117
118 /**
119 * Peeks the next element at the read position w/o modifying pointer, nor blocking.
120 * @return <code>null</code> if empty, otherwise the element which would be read next.
121 */
122 public T peek();
123
124 /**
125 * Peeks the next element at the read position w/o modifying pointer, but w/ blocking.
126 * @return <code>null</code> if empty, otherwise the element which would be read next.
127 */
128 public T peekBlocking() throws InterruptedException;
129
130 /**
131 * Enqueues the given element.
132 * <p>
133 * Returns true if successful, otherwise false in case buffer is full.
134 * </p>
135 * <p>
136 * Method is non blocking and returns immediately;.
137 * </p>
138 */
139 public boolean put(T e);
140
141 /**
142 * Enqueues the given element.
143 * <p>
144 * Method blocks until a free slot becomes available via get.
145 * </p>
146 * @throws InterruptedException
147 */
148 public void putBlocking(T e) throws InterruptedException;
149
150 /**
151 * Enqueues the same element at it's write position, if not full.
152 * <p>
153 * Returns true if successful, otherwise false in case buffer is full.
154 * </p>
155 * <p>
156 * If <code>blocking</code> is true, method blocks until a free slot becomes available via get.
157 * </p>
158 * @param blocking if true, wait until a free slot becomes available via get.
159 * @throws InterruptedException
160 */
161 public boolean putSame(boolean blocking) throws InterruptedException;
162
163 /**
164 * Blocks until at least <code>count</code> free slots become available.
165 * @throws InterruptedException
166 */
167 public void waitForFreeSlots(int count) throws InterruptedException;
168
169 /**
170 * Grows an empty ring buffer, increasing it's capacity about the amount.
171 * <p>
172 * Growing an empty ring buffer increases it's size about the amount, i.e. renders it not empty.
173 * The new elements are inserted at the read position, able to be read out via {@link #get()} etc.
174 * </p>
175 *
176 * @param newElements array of new full elements the empty buffer shall grow about.
177 * @throws IllegalStateException if buffer is not empty
178 * @throws IllegalArgumentException if newElements is null
179 */
180 public void growEmptyBuffer(T[] newElements) throws IllegalStateException, IllegalArgumentException;
181
182 /**
183 * Grows a full ring buffer, increasing it's capacity about the amount.
184 * <p>
185 * Growing a full ring buffer leaves the size intact, i.e. renders it not full.
186 * New <code>null</code> elements are inserted at the write position, able to be written to via {@link #put(Object)} etc.
187 * </p>
188 * @param amount the amount of elements the buffer shall grow about
189 *
190 * @throws IllegalStateException if buffer is not full
191 * @throws IllegalArgumentException if amount is < 0
192 */
193 public void growFullBuffer(int amount) throws IllegalStateException, IllegalArgumentException;
194}
Ring buffer interface, a.k.a circular buffer.
Definition: Ringbuffer.java:45
T peekBlocking()
Peeks the next element at the read position w/o modifying pointer, but w/ blocking.
void growEmptyBuffer(T[] newElements)
Grows an empty ring buffer, increasing it's capacity about the amount.
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.
int size()
Returns the number of elements in this ring buffer.
boolean isFull()
Returns true if this ring buffer is full, otherwise false.
boolean isEmpty()
Returns true if this ring buffer is empty, otherwise false.
void resetFull(T[] copyFrom)
Resets the read and write position according to a full ring buffer and fill all slots w/ elements of ...
int getFreeSlots()
Returns the number of free slots available to put.
void putBlocking(T e)
Enqueues the given element.
T getBlocking()
Dequeues the oldest enqueued element.
String toString()
Returns a short string representation incl.
int capacity()
Returns the net capacity of this ring buffer.
void growFullBuffer(int amount)
Grows a full ring buffer, increasing it's capacity about the amount.
boolean putSame(boolean blocking)
Enqueues the same element at it's write position, if not full.
boolean put(T e)
Enqueues the given element.
void waitForFreeSlots(int count)
Blocks until at least count free slots become available.
void dump(PrintStream stream, String prefix)
Debug functionality - Dumps the contents of the internal array.