net.dempsy.ringbuffer

Class RingBufferControlWorkerPool

java.lang.Object

net.dempsy.ringbuffer.RingBufferControlWorkerPool

public class RingBufferControlWorkerPool
extends Object

This is a helper class for managing a set of RingBufferControls for use in a "single-publisher to multi-consumer" thread configuration where the consumers are workers reading from the queued data.

Currently it would be really bad for Worker consumers to mix availableTo and tryAvailableTo. If a worker uses tryAvailableTo it MUST use tryAvailableTo until tryAvailableTo returns a value that isn't RingBufferConsumerControl.UNAVAILABLE before using availableTo.

Constructor Summary

Constructors

Constructor and Description
RingBufferControlWorkerPool(int sizePowerOfTwo)
RingBufferControlWorkerPool(int sizePowerOfTwo, RingBufferConsumerControl.ConsumerWaitStrategy waitStrategy)

Method Summary

Modifier and Type	Method and Description
void	clear() The RingBufferControlWorkerPool can be cleared or "reset" so that it can be reused from scratch HOWEVER, the workers must be re-retrieved via newWorker(); none of the outstanding workers can be reused.
int	getBufferSize()
long	getNumEntries() This is an estimate of the number of entries currently in the RingBuffer.
int	index(long sequence) This method will convert the sequence to an index of a ring buffer.
boolean	isShutdown() Once the publisher calls RingBufferControl.publishStop() and the consumer acquires it this method will return true.
RingBufferConsumerControl	newWorker()
long	next() This is used by the publishing thread to claim the given number of entries in the buffer all of the underlying RingBufferControls.
void	publish(long sequence) Once the publisher has readied the buffer entries that were claimed, this method allows the subscribers to be notified that they are ready.
long	publishStop() The RingBufferControl can ONLY be stopped from the publish side.
void	removeWorker(RingBufferConsumerControl worker)
long	tryNext() This is used by the publishing thread to claim the next entry in the buffer all of the underlying RingBufferControls.

Methods inherited from class java.lang.Object

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

Constructor Detail

RingBufferControlWorkerPool

public RingBufferControlWorkerPool(int sizePowerOfTwo)

RingBufferControlWorkerPool

public RingBufferControlWorkerPool(int sizePowerOfTwo,
                                   RingBufferConsumerControl.ConsumerWaitStrategy waitStrategy)
                            throws IllegalArgumentException

Throws:

IllegalArgumentException

Method Detail

newWorker

public RingBufferConsumerControl newWorker()

removeWorker

public void removeWorker(RingBufferConsumerControl worker)

next

public long next()

This is used by the publishing thread to claim the given number of entries in the buffer all of the underlying RingBufferControls. The sequence returned should be supplied to the publish(long) command once the publisher thread has prepared the entries.

Returns:

the sequence to provide to the RingBufferControl.publish(long) or the RingBufferConsumerControl.index(long) methods.

tryNext

public long tryNext()

This is used by the publishing thread to claim the next entry in the buffer all of the underlying RingBufferControls. The sequence returned should be supplied to the publish(long) command once the publisher thread has prepared the entries. If there are no currently available slots in the RingBuffer then RingBufferControl.UNAVAILABLE will be returned.

Returns:

the sequence to provide to the RingBufferControl.publish(long) or the RingBufferConsumerControl.index(long) methods.

publish

public void publish(long sequence)

Once the publisher has readied the buffer entries that were claimed, this method allows the subscribers to be notified that they are ready.

Parameters:

sequence - is the sequence returned from the next() or tryNext() call.

publishStop

public long publishStop()

The RingBufferControl can ONLY be stopped from the publish side. The publisher needs to call publishStop to stop the consumer. Once the consumer reaches this point in the sequence, the consumer will receive a RingBufferConsumerControl.ACQUIRE_STOP_REQUEST returned from either RingBufferConsumerControl.availableTo() or RingBufferConsumerControl.tryAvailableTo().

Once that happens the RingBufferConsumerControl.isShutdown() will return true on both the publisher and consumer sides.

Returns:

the sequence that represents where the consumer will be notified to stop.

clear

public void clear()

The RingBufferControlWorkerPool can be cleared or "reset" so that it can be reused from scratch HOWEVER, the workers must be re-retrieved via newWorker(); none of the outstanding workers can be reused. Also, if any outstanding workers are still working when clear() is called they will likely deadlock.

index

public int index(long sequence)

This method will convert the sequence to an index of a ring buffer.

isShutdown

public boolean isShutdown()

Once the publisher calls RingBufferControl.publishStop() and the consumer acquires it this method will return true. It will also return true up until the first sequence is retrieved by a consumer. It will return false at all other times.

getBufferSize

public int getBufferSize()

getNumEntries

public long getNumEntries()

This is an estimate of the number of entries currently in the RingBuffer.