Package 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 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
Author:
Stephen Ostermiller https://ostermiller.org/contact.pl?regarding=Java+Utilities
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    INFINITE_SIZE
    A buffer that will grow as things are added.

  • Constructor Summary

    Constructors
    Constructor
    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
    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

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

  • Field Details

    • INFINITE_SIZE

      public static final int INFINITE_SIZE
      A buffer that will grow as things are added.
      Since:
      ostermillerutils 1.00.00
      See Also:

  • Constructor Details

    • 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 Details

    • 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 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:
      InterruptedException - if the thread is interrupted while waiting.
      Since:
      ostermillerutils 1.00.00

    • read

      public int read(ElementType[] buf) throws 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:
      InterruptedException - if the thread is interrupted while waiting.
      Since:
      ostermillerutils 1.00.00

    • read

      public int read(ElementType[] buf, int off, int len) throws 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:
      InterruptedException - if the thread is interrupted while waiting.
      Since:
      ostermillerutils 1.00.00

    • skip

      public long skip(long n) throws InterruptedException, 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:
      IllegalArgumentException - if n is negative.
      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, IllegalStateException, 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.
      IllegalStateException - if done() has been called.
      InterruptedException - if the write is interrupted.
      Since:
      ostermillerutils 1.00.00

    • write

      public void write(ElementType[] buf, int off, int len) throws BufferOverflowException, IllegalStateException, 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.
      IllegalStateException - if done() has been called.
      InterruptedException - if the write is interrupted.
      Since:
      ostermillerutils 1.00.00

    • write

      public void write(ElementType o) throws BufferOverflowException, IllegalStateException, 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.
      IllegalStateException - if done() has been called.
      InterruptedException - if the write is interrupted.
      Since:
      ostermillerutils 1.00.00