/*
 * Circular Object Buffer
 * Copyright (C) 2002-2010 Stephen Ostermiller
 * http://ostermiller.org/contact.pl?regarding=Java+Utilities
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * See LICENSE.txt for details.
 */
package com.Ostermiller.util;
 
/**
 * Implements the Circular Buffer producer/consumer model for Objects.
 * More information about this class is available from <a target="_top" href=
 * "http://ostermiller.org/utils/CircularObjectBuffer.html">ostermiller.org</a>.
 * <p>
 * This class is thread safe.
 *
 * @see CircularCharBuffer
 * @see CircularByteBuffer
 *
 * @author Stephen Ostermiller http://ostermiller.org/contact.pl?regarding=Java+Utilities
 * @param <ElementType> Type of object allowed in this circular buffer
 * @since ostermillerutils 1.00.00
 */
public class CircularObjectBuffer <ElementType> {
 
    /**
     * The default size for a circular object buffer.
     *
     * @since ostermillerutils 1.00.00
     */
    private final static int DEFAULT_SIZE = 1024;
 
    /**
     * A buffer that will grow as things are added.
     *
     * @since ostermillerutils 1.00.00
     */
    public final static int INFINITE_SIZE = -1;
 
    /**
     * The circular buffer.
     * <p>
     * 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.
     * <p>
     * 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
     */
    protected ElementType[] buffer;
    /**
     * Index of the first Object available to be read.
     *
     * @since ostermillerutils 1.00.00
     */
    protected volatile int readPosition = 0;
    /**
     * Index of the first Object available to be written.
     *
     * @since ostermillerutils 1.00.00
     */
    protected volatile int writePosition = 0;
    /**
     * If this buffer is infinite (should resize itself when full)
     *
     * @since ostermillerutils 1.00.00
     */
    protected volatile boolean infinite = false;
    /**
     * 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
     */
    protected boolean blockingWrite = true;
 
    /**
     * 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
     */
    protected boolean inputDone = false;
 
    /**
     * 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
     */
    public void clear(){
        synchronized (this){
            readPosition = 0;
            writePosition = 0;
            inputDone = false;
        }
    }
 
    /**
     * Get number of Objects that are available to be read.
     * <p>
     * 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.
     *
     * @return the size in Objects of this buffer
     *
     * @since ostermillerutils 1.00.00
     */
    public int getAvailable(){
        synchronized (this){
            return available();
        }
    }
 
    /**
     * Get the number of Objects this buffer has free for
     * writing.
     * <p>
     * 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.
     *
     * @return the available space in Objects of this buffer
     *
     * @since ostermillerutils 1.00.00
     */
    public int getSpaceLeft(){
        synchronized (this){
            return spaceLeft();
        }
    }
 
    /**
     * Get the capacity of this buffer.
     * <p>
     * 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.
     *
     * @return the size in Objects of this buffer
     *
     * @since ostermillerutils 1.00.00
     */
    public int getSize(){
        synchronized (this){
            return buffer.length;
        }
    }
 
    @SuppressWarnings("unchecked") private ElementType[] createArray(int size){
        return (ElementType[]) new Object[size];
    }
 
    /**
     * double the size of the buffer
     *
     * @since ostermillerutils 1.00.00
     */
    private void resize(){
        ElementType[] newBuffer = createArray(buffer.length * 2);
        int available = available();
        if (readPosition <= writePosition){
            // any space between the read and
            // the first write needs to be saved.
            // In this case it is all in one piece.
            int length = writePosition - readPosition;
            System.arraycopy(buffer, readPosition, newBuffer, 0, length);
        } else {
            int length1 = buffer.length - readPosition;
            System.arraycopy(buffer, readPosition, newBuffer, 0, length1);
            int length2 = writePosition;
            System.arraycopy(buffer, 0, newBuffer, length1, length2);
        }
        buffer = newBuffer;
        readPosition = 0;
        writePosition = available;
    }
 
    /**
     * Space available in the buffer which can be written.
     *
     * @since ostermillerutils 1.00.00
     */
    private int spaceLeft(){
        if (writePosition < readPosition){
            // any space between the first write and
            // the read except one Object is available.
            // In this case it is all in one piece.
            return (readPosition - writePosition - 1);
        }
        // space at the beginning and end.
        return ((buffer.length - 1) - (writePosition - readPosition));
    }
 
    /**
     * Objects available for reading.
     *
     * @since ostermillerutils 1.00.00
     */
    private int available(){
        if (readPosition <= writePosition){
            // any space between the first read and
            // the first write is available.  In this case i
            // is all in one piece.
            return (writePosition - readPosition);
        }
        // space at the beginning and end.
        return (buffer.length - (readPosition - writePosition));
    }
 
    /**
     * 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
     */
    public CircularObjectBuffer(){
        this (DEFAULT_SIZE, true);
    }
 
    /**
     * Create a new buffer with given capacity.
     * Writing to a full buffer will block until space
     * is available rather than throw an exception.
     * <p>
     * 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.
     * <p>
     * Note that if the buffer is of INFINITE_SIZE it will
     * neither block or throw exceptions, but rather grow
     * without bound.
     *
     * @param size desired capacity of the buffer in Objects or CircularObjectBuffer.INFINITE_SIZE.
     *
     * @since ostermillerutils 1.00.00
     */
    public CircularObjectBuffer(int size){
        this (size, true);
    }
 
    /**
     * Create a new buffer with a default capacity and
     * given blocking behavior.
     *
     * @param 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
     */
    public CircularObjectBuffer(boolean blockingWrite){
        this (DEFAULT_SIZE, blockingWrite);
    }
 
    /**
     * Create a new buffer with the given capacity and
     * blocking behavior.
     * <p>
     * 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.
     * <p>
     * Note that if the buffer is of INFINITE_SIZE it will
     * neither block or throw exceptions, but rather grow
     * without bound.
     *
     * @param size desired capacity of the buffer in Objects or CircularObjectBuffer.INFINITE_SIZE.
     * @param 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
     */
    public CircularObjectBuffer(int size, boolean blockingWrite){
        if (size == INFINITE_SIZE){
            buffer = createArray(DEFAULT_SIZE);
            infinite = true;
        } else {
            buffer = createArray(size);
            infinite = false;
        }
        this.blockingWrite = blockingWrite;
    }
 
 
    /**
     * 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.
     *
     * @return 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
     */
    public ElementType read() throws InterruptedException {
        while (true){
            synchronized (this){
                int available = available();
                if (available > 0){
                    ElementType result = buffer[readPosition];
                    readPosition++;
                    if (readPosition == buffer.length){
                        readPosition = 0;
                    }
                    return result;
                } else if (inputDone){
                    return null;
                }
            }
            Thread.sleep(100);
        }
    }
 
    /**
     * 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.
     *
     * @param buf Destination buffer.
     * @return 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
     */
    public int read(ElementType[] buf) throws InterruptedException {
        return read(buf, 0, buf.length);
    }
 
    /**
     * 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.
     *
     * @param buf Destination buffer.
     * @param off Offset at which to start storing Objects.
     * @param len Maximum number of Objects to read.
     * @return 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
     */
    public int read(ElementType[] buf, int off, int len) throws InterruptedException {
        while (true){
            synchronized (this){
                int available = available();
                if (available > 0){
                    int length = Math.min(len, available);
                    int firstLen = Math.min(length, buffer.length - readPosition);
                    int secondLen = length - firstLen;
                    System.arraycopy(buffer, readPosition, buf, off, firstLen);
                    if (secondLen > 0){
                        System.arraycopy(buffer, 0, buf, off+firstLen,  secondLen);
                        readPosition = secondLen;
                    } else {
                        readPosition += length;
                    }
                    if (readPosition == buffer.length) {
                        readPosition = 0;
                    }
                    return length;
                } else if (inputDone){
                    return -1;
                }
            }
            Thread.sleep(100);
        }
    }
 
 
    /**
     * 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.
     *
     * @param n The number of Objects to skip
     * @return The number of Objects actually skipped
     * @throws IllegalArgumentException if n is negative.
     * @throws InterruptedException if the thread is interrupted while waiting.
     *
     * @since ostermillerutils 1.00.00
     */
    public long skip(long n) throws InterruptedException, IllegalArgumentException {
        while (true){
            synchronized (this){
                int available = available();
                if (available > 0){
                    int length = Math.min((int)n, available);
                    int firstLen = Math.min(length, buffer.length - readPosition);
                    int secondLen = length - firstLen;
                    if (secondLen > 0){
                        readPosition = secondLen;
                    } else {
                        readPosition += length;
                    }
                    if (readPosition == buffer.length) {
                        readPosition = 0;
                    }
                    return length;
                } else if (inputDone){
                    return 0;
                }
            }
            Thread.sleep(100);
        }
    }
 
    /**
     * 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.
     * <p>
     * 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
     */
    public void done(){
        synchronized (this){
            inputDone = true;
        }
    }
 
    /**
     * 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.
     *
     * @param 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.
     * @throws IllegalStateException if done() has been called.
     * @throws InterruptedException if the write is interrupted.
     *
     * @since ostermillerutils 1.00.00
     */
    public void write(ElementType[] buf) throws BufferOverflowException, IllegalStateException, InterruptedException {
        write(buf, 0, buf.length);
    }
 
    /**
     * 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.
     *
     * @param buf Array of Objects
     * @param off Offset from which to start writing Objects
     * @param 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.
     * @throws IllegalStateException if done() has been called.
     * @throws InterruptedException if the write is interrupted.
     *
     * @since ostermillerutils 1.00.00
     */
    public void write(ElementType[] buf, int off, int len) throws BufferOverflowException, IllegalStateException, InterruptedException {
        while (len > 0){
            synchronized (CircularObjectBuffer.this){
                if (inputDone) throw new IllegalStateException("CircularObjectBuffer.done() has been called, CircularObjectBuffer.write() failed.");
                int spaceLeft = spaceLeft();
                while (infinite && spaceLeft < len){
                    resize();
                    spaceLeft = spaceLeft();
                }
                if (!blockingWrite && spaceLeft < len) throw new BufferOverflowException("CircularObjectBuffer is full; cannot write " + len + " Objects");
                int realLen = Math.min(len, spaceLeft);
                int firstLen = Math.min(realLen, buffer.length - writePosition);
                int secondLen = Math.min(realLen - firstLen, buffer.length - readPosition - 1);
                int written = firstLen + secondLen;
                if (firstLen > 0){
                    System.arraycopy(buf, off, buffer, writePosition, firstLen);
                }
                if (secondLen > 0){
                    System.arraycopy(buf, off+firstLen, buffer, 0, secondLen);
                    writePosition = secondLen;
                } else {
                    writePosition += written;
                }
                if (writePosition == buffer.length) {
                    writePosition = 0;
                }
                off += written;
                len -= written;
            }
            if (len > 0){
                Thread.sleep(100);
            }
        }
    }
 
    /**
     * 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.
     *
     * @param 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.
     * @throws IllegalStateException if done() has been called.
     * @throws InterruptedException if the write is interrupted.
     *
     * @since ostermillerutils 1.00.00
     */
    public void write(ElementType o) throws BufferOverflowException, IllegalStateException, InterruptedException {
        boolean written = false;
        while (!written){
            synchronized (CircularObjectBuffer.this){
                if (inputDone) throw new IllegalStateException("CircularObjectBuffer.done() has been called, CircularObjectBuffer.write() failed.");
                int spaceLeft = spaceLeft();
                while (infinite && spaceLeft < 1){
                    resize();
                    spaceLeft = spaceLeft();
                }
                if (!blockingWrite && spaceLeft < 1) throw new BufferOverflowException("CircularObjectBuffer is full; cannot write 1 Object");
                if (spaceLeft > 0){
                    buffer[writePosition] = o;
                    writePosition++;
                    if (writePosition == buffer.length) {
                        writePosition = 0;
                    }
                    written = true;
                }
            }
            if (!written){
                Thread.sleep(100);
            }
        }
    }
}