org.michailov.async.io

Class RingBuffer

java.lang.Object

org.michailov.async.io.RingBuffer

Direct Known Subclasses:

ByteRingBuffer, CharRingBuffer, StringRingBuffer

public abstract class RingBuffer
extends java.lang.Object

This class defines an abstract ring buffer functionality where a virtual read position and a virtual write position chase each other around a buffer length. The type of the items in the buffer is irrelevant to this functionality.

The virtual write position is always "ahead" of the virtual read position. That is because something has to be written first before it could be read.

Thread safety: This functionality is safe to be used by one "reader" thread and one "writer" thread concurrently as long as the reader thread only updates the virtual read position (it's OK to get the virtual write position) and the "writer" thread only updates the virtual write position (it's OK to get the virtual read position.)

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RingBuffer(int bufferLength) Constructor to be called from concrete implementations.

Method Summary

Modifier and Type	Method and Description
int	advanceReadPosition(int delta) This method must be called to indicate a successful read operation.
int	advanceWritePosition(int delta) This method must be called to indicate a successful write operation.
int	getAvailableToRead() Gets the count of items that are available to be read.
int	getAvailableToReadStraight() Gets the count of items that are available to be read at once.
int	getAvailableToWrite() Gets the count of items that are available to be written.
int	getAvailableToWriteStraight() Gets the count of items that are available to be written at once.
int	getBufferLength() Gets the length of the underlying buffer.
int	getReadPosition() Gets the current virtual read position.
long	getTotalReadCount() Gets the total count of read items.
long	getTotalWriteCount() Gets the total count of written items.
int	getWritePosition() Gets the current virtual write position.
boolean	isEOF() Gets the EOF state of this ring buffer.
void	setEOF() Sets the EOF state of this ring buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

RingBuffer

protected RingBuffer(int bufferLength)

Constructor to be called from concrete implementations.

Parameters:

bufferLength - Length of the underlying buffer.

Method Detail

isEOF

public boolean isEOF()

Gets the EOF state of this ring buffer. The EOF state is explicitly set by a writing client.

Returns:

true iff no more bytes will be written to this ring buffer.

setEOF

public void setEOF()

Sets the EOF state of this ring buffer. The EOF state is explicitly set by a writing client.

getBufferLength

public int getBufferLength()

Gets the length of the underlying buffer.

Returns:

The length of the underlying buffer.

getReadPosition

public int getReadPosition()

Gets the current virtual read position.

Returns:

The current virtual read position.

getWritePosition

public int getWritePosition()

Gets the current virtual write position.

Returns:

The current virtual write position.

getTotalReadCount

public long getTotalReadCount()

Gets the total count of read items.

Returns:

The total count of read items.

getTotalWriteCount

public long getTotalWriteCount()

Gets the total count of written items.

Returns:

The total count of written items.

getAvailableToRead

public int getAvailableToRead()

Gets the count of items that are available to be read. Reading these items may include a flip over, i.e. these items can be read one by one, but not necessarily all at once. To get the items that can be read at once, see getAvailableToReadStraight().

Returns:

The count of items available to be read one by one.

getAvailableToReadStraight

public int getAvailableToReadStraight()

Gets the count of items that are available to be read at once. This method is useful to be used with APIs that do buffer copying. This count is less than or equal to the count returned from getAvailableToRead().

Returns:

The count of items available to be read at once.

getAvailableToWrite

public int getAvailableToWrite()

Gets the count of items that are available to be written. Writing these items may include a flip over, i.e. these items can be written one by one, but not necessarily all at once. To get the items that can be written at once, see getAvailableToWriteStraight().

Returns:

The count of items available to be written one by one.

getAvailableToWriteStraight

public int getAvailableToWriteStraight()

Gets the count of items that are available to be written at once. This method is useful to be used with APIs that do buffer copying. This count is less than or equal to the count returned from getAvailableToWrite().

Returns:

The count of items available to be written at once.

advanceReadPosition

public int advanceReadPosition(int delta)

This method must be called to indicate a successful read operation. If multiple items are read one by one, it is not necessary to advance the read position after each item. That could be done once for all read items.

An attempt to advance the read position beyond the value returned by getAvailableToRead() limits the attempt to the value of getAvailableToRead(). That is not an exceptional case.

Parameters:

delta - The count of virtual notches by which to increment the virtual read position.

Returns:

The minimum of the requested delta and the value of getAvailableToRead().

advanceWritePosition

public int advanceWritePosition(int delta)

This method must be called to indicate a successful write operation. If multiple items are written one by one, it is not necessary to advance the write position after each item. That could be done once for all written items.

An attempt to advance the write position beyond the value returned by getAvailableToWrite() limits the attempt to the value of getAvailableToWrite(). That is not an exceptional case.

Parameters:

delta - The count of virtual notches by which to increment the virtual write position.

Returns:

The minimum of the requested delta and the value of getAvailableToWrite().