com.Ostermiller.util
Class CircularObjectBuffer<ElementType>

java.lang.Object
  extended by 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
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
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
 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