org.jlab.coda.emu.support.data

Class ByteBufferSupply

java.lang.Object

org.jlab.coda.emu.support.data.ByteBufferSupply

public class ByteBufferSupply
extends java.lang.Object

This class is used to provide a very fast supply of ByteBuffer objects (actually ByteBufferItem objects each of which wraps a ByteBuffer) for reuse in 3 different modes (uses Disruptor software package).

1) It can be used as a simple supply of ByteBuffer(Item)s. In this mode, only get() and release() are called. A user does a get(), uses that buffer, then calls release() when done with it. If there are multiple users of a single buffer (say 5), then call bufferItem.setUsers(5) before it is used and the buffer is only released when all 5 users have called release().

2) As in the first usage, it can be used as a supply of ByteBuffers, but each buffer can be preset to a specific ByteBuffer object. Thus it can act as a supply of buffers in which each contains specific data. Because of the circular nature of the ring used to implement this code, after all ByteBuffers have been gotten by the user for the first time, it starts back over with the first -- going round and round.

To implement this, use the constructor which takes a list of ByteBuffer objects with which to fill this supply. The user does a getAsIs() which does not clear the buffer's position and limit. When finished reading/writing, user calls release(). It's up to the user to maintain proper values for the buffer's position and limit since it will be used again. If there are multiple users of a single buffer (say 5), then call bufferItem.setUsers(5) before it is used and the buffer is only released when all 5 users have called release().

3) It can be used as a supply of ByteBuffers in which a single producer provides data for a single consumer which is waiting for that data. The producer does a get(), fills the buffer with data, and finally does a publish() to let the consumer know the data is ready. Simultaneously, a consumer does a consumerGet() to access the data once it is ready. The consumer then calls release() when finished which allows the producer to reuse the now unused buffer.

Author:

timmer (4/7/14)

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.Object	auxObject Object to be associated with each ByteBufferItem.

Constructor Summary

Constructors

Constructor and Description
ByteBufferSupply(int ringSize, int bufferSize) Constructor.
ByteBufferSupply(int ringSize, int bufferSize, java.nio.ByteOrder order, boolean direct) Constructor.
ByteBufferSupply(int ringSize, int bufferSize, java.nio.ByteOrder order, boolean direct, boolean orderedRelease) Constructor.
ByteBufferSupply(int ringSize, int bufferSize, java.nio.ByteOrder order, boolean direct, boolean orderedRelease, org.jlab.coda.jevio.EvioNodePool[] pools) Constructor.
ByteBufferSupply(int ringSize, java.util.List<java.nio.ByteBuffer> bufList, boolean orderedRelease) Constructor.

Method Summary

Modifier and Type	Method and Description
ByteBufferItem	consumerGet() Get the next available item in ring buffer for getting data already written into.
ByteBufferItem	get() Get the next available item in ring buffer for writing/reading data.
ByteBufferItem	getAsIs() Get the next available item in ring buffer for writing/reading data.
int	getFillLevel() What percentage of the byte buffers are being used? If this ring is full (of unused buffers), it corresponds to an empty input or output channel (0%).
void	publish(ByteBufferItem byteBufferItem) Used to tell that the consumer that the ring buffer item is ready for consumption.
void	release(ByteBufferItem item) Consumer releases claim on the given ring buffer item so it becomes available for reuse.

Methods inherited from class java.lang.Object

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

Field Detail

auxObject

public java.lang.Object auxObject

Object to be associated with each ByteBufferItem.

Constructor Detail

ByteBufferSupply

public ByteBufferSupply(int ringSize,
                        int bufferSize)
                 throws java.lang.IllegalArgumentException

Constructor. Buffers are big endian and not direct.

Parameters:

ringSize - number of ByteBufferItem objects in ring buffer.

bufferSize - initial size (bytes) of ByteBuffer in each ByteBufferItem object.

Throws:

java.lang.IllegalArgumentException - if args < 1 or ringSize not power of 2.

ByteBufferSupply

public ByteBufferSupply(int ringSize,
                        int bufferSize,
                        java.nio.ByteOrder order,
                        boolean direct)
                 throws java.lang.IllegalArgumentException

Constructor.

Parameters:

ringSize - number of ByteBufferItem objects in ring buffer.

bufferSize - initial size (bytes) of ByteBuffer in each ByteBufferItem object.

order - byte order of ByteBuffer in each ByteBufferItem object.

direct - if true, make ByteBuffers direct.

Throws:

java.lang.IllegalArgumentException - if args < 1 or ringSize not power of 2.

ByteBufferSupply

public ByteBufferSupply(int ringSize,
                        int bufferSize,
                        java.nio.ByteOrder order,
                        boolean direct,
                        boolean orderedRelease)
                 throws java.lang.IllegalArgumentException

Constructor. Used when wanting to avoid locks for speed purposes. Say a ByteBufferItem is used by several users. This is true in ET or emu input channels in which many evio events all contain a reference to the same buffer. If the user can guarantee that all the users of one buffer release it before any of the users of the next, then synchronization is not necessary. If that isn't the case, then locks take care of preventing a later acquired buffer from being released first and consequently everything that came before it in the ring.

Parameters:

ringSize - number of ByteBufferItem objects in ring buffer.

bufferSize - initial size (bytes) of ByteBuffer in each ByteBufferItem object.

order - byte order of ByteBuffer in each ByteBufferItem object.

direct - if true, make ByteBuffers direct.

orderedRelease - if true, the user promises to release the ByteBufferItems in the same order as acquired. This avoids using synchronized code (no locks).

Throws:

java.lang.IllegalArgumentException - if args < 1 or ringSize not power of 2.

ByteBufferSupply

public ByteBufferSupply(int ringSize,
                        int bufferSize,
                        java.nio.ByteOrder order,
                        boolean direct,
                        boolean orderedRelease,
                        org.jlab.coda.jevio.EvioNodePool[] pools)
                 throws java.lang.IllegalArgumentException

Constructor. Used when wanting to avoid locks for speed purposes. Say a ByteBufferItem is used by several users. This is true in ET or emu input channels in which many evio events all contain a reference to the same buffer. If the user can guarantee that all the users of one buffer release it before any of the users of the next, then synchronization is not necessary. If that isn't the case, then locks take care of preventing a later acquired buffer from being released first and consequently everything that came before it in the ring.

In addition, each ByteBufferItem in this supply will have an object associated with it which is passed in through the last argument. Used to store an EvioNodePool with each buffer in the supply.

Parameters:

ringSize - number of ByteBufferItem objects in ring buffer.

bufferSize - initial size (bytes) of ByteBuffer in each ByteBufferItem object.

order - byte order of ByteBuffer in each ByteBufferItem object.

direct - if true, make ByteBuffers direct.

orderedRelease - if true, the user promises to release the ByteBufferItems in the same order as acquired. This avoids using synchronized code (no locks).

pools - one EvioNodePool for each ByteBuffer.

Throws:

java.lang.IllegalArgumentException - if args < 1 or ringSize not power of 2, pools array must have not be null or have less than ringSize number of elements.

ByteBufferSupply

public ByteBufferSupply(int ringSize,
                        java.util.List<java.nio.ByteBuffer> bufList,
                        boolean orderedRelease)
                 throws java.lang.IllegalArgumentException

Constructor. Used when wanting a source of ByteBuffers which already contain data. Useful when testing.

Parameters:

ringSize - number of ByteBufferItem objects in ring buffer.

bufList - list of ByteBuffers used to populate this supply. List must contain ringSize number of buffers.

orderedRelease - if true, the user promises to release the ByteBufferItems in the same order as acquired. This avoids using synchronized code (no locks).

Throws:

java.lang.IllegalArgumentException - bad arg or ringSize not power of 2.

Method Detail

getFillLevel

public int getFillLevel()

What percentage of the byte buffers are being used? If this ring is full (of unused buffers), it corresponds to an empty input or output channel (0%). In this case, (ringSize - (ringSize - (produced - consumed))) = (produced - consumed) = 0. If it's empty then the channel is full (100%). In this case, (produced - consumed) = ringSize.

Returns:

fill level, 0% to 100%.

get

public ByteBufferItem get()
                   throws java.lang.InterruptedException

Get the next available item in ring buffer for writing/reading data. Not sure if this method is thread-safe.

Returns:

next available item in ring buffer.

Throws:

java.lang.InterruptedException - if thread interrupted.

getAsIs

public ByteBufferItem getAsIs()
                       throws java.lang.InterruptedException

Get the next available item in ring buffer for writing/reading data. Does not set the ByteBuffer to position = 0 and limit = capacity. In other words, it facilitates reading existing data from the buffer. When finished with this item, it's up to the user to set position and limit to the correct value for the next user. Not sure if this method is thread-safe.

Returns:

next available item in ring buffer.

Throws:

java.lang.InterruptedException - if thread interrupted.

consumerGet

public ByteBufferItem consumerGet()
                           throws java.lang.InterruptedException

Get the next available item in ring buffer for getting data already written into. Not sure if this method is thread-safe.

Returns:

next available item in ring buffer for getting data already written into.

Throws:

java.lang.InterruptedException - if thread interrupted.

release

public void release(ByteBufferItem item)

Consumer releases claim on the given ring buffer item so it becomes available for reuse. This method ensures that sequences are released in order and is thread-safe. To be used in conjunction with get() and consumerGet().

Parameters:

item - item in ring buffer to release for reuse.

publish

public void publish(ByteBufferItem byteBufferItem)

Used to tell that the consumer that the ring buffer item is ready for consumption. Not sure if this method is thread-safe. To be used in conjunction with get() and consumerGet().

Parameters:

byteBufferItem - item available for consumer's use.