com.Ostermiller.util

Class CircularObjectBuffer<ElementType>

java.lang.Object

com.Ostermiller.util.CircularObjectBuffer<ElementType>

Type Parameters:

ElementType - Type of object allowed in this circular buffer

public class CircularObjectBuffer<ElementType>
extends java.lang.Object

Implements the Circular Buffer producer/consumer model for Objects. More information about this class is available from ostermiller.org.

This class is thread safe.

Since:

ostermillerutils 1.00.00

See Also:

CircularCharBuffer, CircularByteBuffer

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	blockingWrite True if a write to a full buffer should block until the buffer has room, false if the write method should throw an IOException
protected ElementType[]	buffer The circular buffer.
protected boolean	infinite If this buffer is infinite (should resize itself when full)
static int	INFINITE_SIZE A buffer that will grow as things are added.
protected boolean	inputDone True when no more input is coming into this buffer.
protected int	readPosition Index of the first Object available to be read.
protected int	writePosition Index of the first Object available to be written.

Constructor Summary

Constructors

Constructor and Description
CircularObjectBuffer() Create a new buffer with a default capacity.
CircularObjectBuffer(boolean blockingWrite) Create a new buffer with a default capacity and given blocking behavior.
CircularObjectBuffer(int size) Create a new buffer with given capacity.
CircularObjectBuffer(int size, boolean blockingWrite) Create a new buffer with the given capacity and blocking behavior.

Method Summary

Modifier and Type	Method and Description
void	clear() Make this buffer ready for reuse.
void	done() This method should be used by the producer to signal to the consumer that the producer is done producing objects and that the consumer should stop asking for objects once it has used up buffered objects.
int	getAvailable() Get number of Objects that are available to be read.
int	getSize() Get the capacity of this buffer.
int	getSpaceLeft() Get the number of Objects this buffer has free for writing.
ElementType	read() Get a single Object from this buffer.
int	read(ElementType[] buf) Get Objects into an array from this buffer.
int	read(ElementType[] buf, int off, int len) Get Objects into a portion of an array from this buffer.
long	skip(long n) Skip Objects.
void	write(ElementType o) Add a single Object to this buffer.
void	write(ElementType[] buf) Fill this buffer with array of Objects.
void	write(ElementType[] buf, int off, int len) Fill this buffer with a portion of an array of Objects.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INFINITE_SIZE

public static final int INFINITE_SIZE

A buffer that will grow as things are added.

Since:

ostermillerutils 1.00.00

See Also:

Constant Field Values

buffer

protected ElementType[] buffer

The circular buffer.

The actual capacity of the buffer is one less than the actual length of the buffer so that an empty and a full buffer can be distinguished. An empty buffer will have the readPostion and the writePosition equal to each other. A full buffer will have the writePosition one less than the readPostion.

There are two important indexes into the buffer: The readPosition, and the writePosition. The Objects available to be read go from the readPosition to the writePosition, wrapping around the end of the buffer. The space available for writing goes from the write position to one less than the readPosition, wrapping around the end of the buffer.

Since:

ostermillerutils 1.00.00

readPosition

protected volatile int readPosition

Index of the first Object available to be read.

Since:

ostermillerutils 1.00.00

writePosition

protected volatile int writePosition

Index of the first Object available to be written.

Since:

ostermillerutils 1.00.00

infinite

protected volatile boolean infinite

If this buffer is infinite (should resize itself when full)

Since:

ostermillerutils 1.00.00

blockingWrite

protected boolean blockingWrite

True if a write to a full buffer should block until the buffer has room, false if the write method should throw an IOException

Since:

ostermillerutils 1.00.00

inputDone

protected boolean inputDone

True when no more input is coming into this buffer. At that point reading from the buffer may return null if the buffer is empty, otherwise a read will block until an Object is available.

Since:

ostermillerutils 1.00.00

Constructor Detail

CircularObjectBuffer

public CircularObjectBuffer()

Create a new buffer with a default capacity. Writing to a full buffer will block until space is available rather than throw an exception.

Since:

ostermillerutils 1.00.00

CircularObjectBuffer

public CircularObjectBuffer(int size)

Create a new buffer with given capacity. Writing to a full buffer will block until space is available rather than throw an exception.

Note that the buffer may reserve some Objects for special purposes and capacity number of Objects may not be able to be written to the buffer.

Note that if the buffer is of INFINITE_SIZE it will neither block or throw exceptions, but rather grow without bound.

Parameters:

size - desired capacity of the buffer in Objects or CircularObjectBuffer.INFINITE_SIZE.

Since:

ostermillerutils 1.00.00

CircularObjectBuffer

public CircularObjectBuffer(boolean blockingWrite)

Create a new buffer with a default capacity and given blocking behavior.

Parameters:

blockingWrite - true writing to a full buffer should block until space is available, false if an exception should be thrown instead.

Since:

ostermillerutils 1.00.00

CircularObjectBuffer

public CircularObjectBuffer(int size,
                            boolean blockingWrite)

Create a new buffer with the given capacity and blocking behavior.

Note that the buffer may reserve some Objects for special purposes and capacity number of Objects may not be able to be written to the buffer.

Note that if the buffer is of INFINITE_SIZE it will neither block or throw exceptions, but rather grow without bound.

Parameters:

size - desired capacity of the buffer in Objects or CircularObjectBuffer.INFINITE_SIZE.

blockingWrite - true writing to a full buffer should block until space is available, false if an exception should be thrown instead.

Since:

ostermillerutils 1.00.00

Method Detail

clear

public void clear()

Make this buffer ready for reuse. The contents of the buffer will be cleared and the streams associated with this buffer will be reopened if they had been closed.

Since:

ostermillerutils 1.00.00

getAvailable

public int getAvailable()

Get number of Objects that are available to be read.

Note that the number of Objects available plus the number of Objects free may not add up to the capacity of this buffer, as the buffer may reserve some space for other purposes.

Returns:

the size in Objects of this buffer

Since:

ostermillerutils 1.00.00

getSpaceLeft

public int getSpaceLeft()

Get the number of Objects this buffer has free for writing.

Note that the number of Objects available plus the number of Objects free may not add up to the capacity of this buffer, as the buffer may reserve some space for other purposes.

Returns:

the available space in Objects of this buffer

Since:

ostermillerutils 1.00.00

getSize

public int getSize()

Get the capacity of this buffer.

Note that the number of Objects available plus the number of Objects free may not add up to the capacity of this buffer, as the buffer may reserve some space for other purposes.

Returns:

the size in Objects of this buffer

Since:

ostermillerutils 1.00.00

read

public ElementType read()
                 throws java.lang.InterruptedException

Get a single Object from this buffer. This method should be called by the consumer. This method will block until a Object is available or no more objects are available.

Returns:

The Object read, or null if there are no more objects

Throws:

java.lang.InterruptedException - if the thread is interrupted while waiting.

Since:

ostermillerutils 1.00.00

read

public int read(ElementType[] buf)
         throws java.lang.InterruptedException

Get Objects into an array from this buffer. This method should be called by the consumer. This method will block until some input is available, or there is no more input.

Parameters:

buf - Destination buffer.

Returns:

The number of Objects read, or -1 there will be no more objects available.

Throws:

java.lang.InterruptedException - if the thread is interrupted while waiting.

Since:

ostermillerutils 1.00.00

read

public int read(ElementType[] buf,
                int off,
                int len)
         throws java.lang.InterruptedException

Get Objects into a portion of an array from this buffer. This method should be called by the consumer. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

Parameters:

buf - Destination buffer.

off - Offset at which to start storing Objects.

len - Maximum number of Objects to read.

Returns:

The number of Objects read, or -1 there will be no more objects available.

Throws:

java.lang.InterruptedException - if the thread is interrupted while waiting.

Since:

ostermillerutils 1.00.00

skip

public long skip(long n)
          throws java.lang.InterruptedException,
                 java.lang.IllegalArgumentException

Skip Objects. This method should be used by the consumer when it does not care to examine some number of Objects. This method will block until some Objects are available, or there will be no more Objects available.

Parameters:

n - The number of Objects to skip

Returns:

The number of Objects actually skipped

Throws:

java.lang.IllegalArgumentException - if n is negative.

java.lang.InterruptedException - if the thread is interrupted while waiting.

Since:

ostermillerutils 1.00.00

done

public void done()

This method should be used by the producer to signal to the consumer that the producer is done producing objects and that the consumer should stop asking for objects once it has used up buffered objects.

Once the producer has signaled that it is done, further write() invocations will cause an IllegalStateException to be thrown. Calling done() multiple times, however, has no effect.

Since:

ostermillerutils 1.00.00

write

public void write(ElementType[] buf)
           throws BufferOverflowException,
                  java.lang.IllegalStateException,
                  java.lang.InterruptedException

Fill this buffer with array of Objects. This method should be called by the producer. If the buffer allows blocking writes, this method will block until all the data has been written rather than throw a BufferOverflowException.

Parameters:

buf - Array of Objects to be written

Throws:

BufferOverflowException - if buffer does not allow blocking writes and the buffer is full. If the exception is thrown, no data will have been written since the buffer was set to be non-blocking.

java.lang.IllegalStateException - if done() has been called.

java.lang.InterruptedException - if the write is interrupted.

Since:

ostermillerutils 1.00.00

write

public void write(ElementType[] buf,
                  int off,
                  int len)
           throws BufferOverflowException,
                  java.lang.IllegalStateException,
                  java.lang.InterruptedException

Fill this buffer with a portion of an array of Objects. This method should be called by the producer. If the buffer allows blocking writes, this method will block until all the data has been written rather than throw an IOException.

Parameters:

buf - Array of Objects

off - Offset from which to start writing Objects

len - - Number of Objects to write

Throws:

BufferOverflowException - if buffer does not allow blocking writes and the buffer is full. If the exception is thrown, no data will have been written since the buffer was set to be non-blocking.

java.lang.IllegalStateException - if done() has been called.

java.lang.InterruptedException - if the write is interrupted.

Since:

ostermillerutils 1.00.00

write

public void write(ElementType o)
           throws BufferOverflowException,
                  java.lang.IllegalStateException,
                  java.lang.InterruptedException

Add a single Object to this buffer. This method should be called by the producer. If the buffer allows blocking writes, this method will block until all the data has been written rather than throw an IOException.

Parameters:

o - Object to be written.

Throws:

BufferOverflowException - if buffer does not allow blocking writes and the buffer is full. If the exception is thrown, no data will have been written since the buffer was set to be non-blocking.

java.lang.IllegalStateException - if done() has been called.

java.lang.InterruptedException - if the write is interrupted.

Since:

ostermillerutils 1.00.00