RingBufferConsumerControl (Dempsy Commons Aggregator 2.1.2 API)

java.lang.Object
- net.dempsy.ringbuffer.RingBufferConsumerControl

Direct Known Subclasses:

RingBufferControl
```
public abstract class RingBufferConsumerControl
extends Object
```
This code is substantially based on the ingenious work done by Martin Thompson on what he calls "Mechanical Sympathy." It leans heavily on the source code from version 3.0.0.beta2 of the LMAX-exchange Disruptor but has been completely refactored in order to invert separate the control mechanism from what is being controlled and to simplify the API.

For more information on the LMAX Disruptor, see:
```
 http://lmax-exchange.github.com/disruptor/
 
```
Employ Martin Thompson's "mechanical sympathy" to the concurrency control mechanism for a ring buffer. It directly borrows from their code base and as of the time this class was written, it has about 20-30% more throughput than their own ring buffer as measured by their own OneToOne benchmark test and about 15x faster as measured on their ThreeToOne test (on my machine, 64bit Linux, 64bit Java 6 Jvm).

This class is incredibly temperamental and must strictly be used the way it was intended. Misuse can easily lead to lockups, missed sequences, etc.

In general, the RingBufferControl is the logic that controls the entries in a ring buffer, but not the ring buffer itself. These classes make no assumptions about where the data is stored (other than in physical memory), or what type it is.

The RingBufferControl is completely analogous to a traditional "condition variable." Just like a Condition Variable is the synchronization mechanism that gates concurrent access to some 'condition', but says nothing about what the 'condition' actually is, the RingBufferControl gates concurrent access to the publishing and consuming of data in a ring buffer.

The 'consumer side' control and the 'publishing side' control are broken into two separate classes. This class represents control of the consumer side of the ring buffer. while RingBufferControl additionally contains the publish side control.

These two base primitives can only be used with one consuming thread and one publishing thread, however, they form the building blocks for several other configurations (see RingBufferControlMulticaster and RingBufferControlMultiplexor)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`RingBufferConsumerControl.ConsumerWaitStrategy` This interface can be implemented to provide various custom wait strategies for the consumer side of the control.

Field Summary

Fields
Modifier and Type	Field and Description
`static long`	`ACQUIRE_STOP_REQUEST` This value can be returned from `availableTo()` or `tryAvailableTo()` to inform the consumer that the published has called `RingBufferControl.publishStop()`
`protected int`	`bufferSize`
`protected int`	`indexMask`
`protected static long`	`INITIAL_CURSOR_VALUE` Set to -1 as sequence starting point
`protected Iterator`	`iter`
`long`	`p1` Making this public avoids it being optimized away
`long`	`p2` Making this public avoids it being optimized away
`long`	`p3` Making this public avoids it being optimized away
`long`	`p4` Making this public avoids it being optimized away
`long`	`p5` Making this public avoids it being optimized away
`long`	`p6` Making this public avoids it being optimized away
`protected com.lmax.disruptor.Sequence`	`publishCursor`
`static RingBufferConsumerControl.ConsumerWaitStrategy`	`spin` Using this strategy provides 'spin' approach to waiting for data to be available for the consumer.
`protected com.lmax.disruptor.util.PaddedLong`	`stop`
`protected boolean`	`stopIsCommon`
`protected com.lmax.disruptor.Sequence`	`tail`
`static long`	`UNAVAILABLE` This value can be returned from `tryAvailableTo()` to indicate that there are no pending published values available.
`protected RingBufferConsumerControl.ConsumerWaitStrategy`	`waitStrategy`
`static RingBufferConsumerControl.ConsumerWaitStrategy`	`yield` Using this strategy provides 'yield' approach to waiting for data to be available for the consumer.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`RingBufferConsumerControl(int sizePowerOfTwo, RingBufferConsumerControl.ConsumerWaitStrategy waitStrategy, com.lmax.disruptor.Sequence cursor)`
`protected`	`RingBufferConsumerControl(int sizePowerOfTwo, RingBufferConsumerControl.ConsumerWaitStrategy waitStrategy, com.lmax.disruptor.Sequence cursor, com.lmax.disruptor.util.PaddedLong commonStop)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`long`	`availableTo()` `availableTo()` is a consumer side call that will block using the wait strategy until a value (or several) have been published.
`protected long`	`availableTo(long requestedSequence)`
`protected void`	`clear()`
`<T> Iterable<T>`	`consumeAsIterable(T[] values)`
`<T> Iterator<T>`	`consumeAsIterator(T[] values)`
`protected void`	`doNotifyProcessed(long sequence)`
`protected com.lmax.disruptor.Sequence`	`getTail()`
`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`.
`void`	`notifyProcessed()` This method must be called by the consumer once the consumer is finished with the currently published results.
`long`	`sumPaddingToPreventOptimisation()`
`long`	`tryAvailableTo()` This method allows the consumer side to poll for publishing events.
`protected long`	`tryAvailableTo(long requestedSequence)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - INITIAL_CURSOR_VALUE
```
protected static final long INITIAL_CURSOR_VALUE
```
    Set to -1 as sequence starting point
    
    See Also:
    
    Constant Field Values
  - ACQUIRE_STOP_REQUEST
```
public static final long ACQUIRE_STOP_REQUEST
```
    This value can be returned from availableTo() or tryAvailableTo() to inform the consumer that the published has called RingBufferControl.publishStop()
    
    See Also:
    
    Constant Field Values
  - UNAVAILABLE
```
public static final long UNAVAILABLE
```
    This value can be returned from tryAvailableTo() to indicate that there are no pending published values available.
    
    See Also:
    
    Constant Field Values
  - spin
```
public static final RingBufferConsumerControl.ConsumerWaitStrategy spin
```
    Using this strategy provides 'spin' approach to waiting for data to be available for the consumer.
  - yield
```
public static final RingBufferConsumerControl.ConsumerWaitStrategy yield
```
    Using this strategy provides 'yield' approach to waiting for data to be available for the consumer. It starts by spinning but quickly backs off to yielding the thread in between polls.
  - bufferSize
```
protected final int bufferSize
```
  - indexMask
```
protected final int indexMask
```
  - waitStrategy
```
protected final RingBufferConsumerControl.ConsumerWaitStrategy waitStrategy
```
  - publishCursor
```
protected final com.lmax.disruptor.Sequence publishCursor
```
  - tail
```
protected final com.lmax.disruptor.Sequence tail
```
  - stop
```
protected final com.lmax.disruptor.util.PaddedLong stop
```
  - stopIsCommon
```
protected boolean stopIsCommon
```
  - p1
```
public volatile long p1
```
    Making this public avoids it being optimized away
  - p2
```
public volatile long p2
```
    Making this public avoids it being optimized away
  - p3
```
public volatile long p3
```
    Making this public avoids it being optimized away
  - p4
```
public volatile long p4
```
    Making this public avoids it being optimized away
  - p5
```
public volatile long p5
```
    Making this public avoids it being optimized away
  - p6
```
public volatile long p6
```
    Making this public avoids it being optimized away
  - iter
```
protected Iterator iter
```
- Constructor Detail
  - RingBufferConsumerControl
```
protected RingBufferConsumerControl(int sizePowerOfTwo,
                                    RingBufferConsumerControl.ConsumerWaitStrategy waitStrategy,
                                    com.lmax.disruptor.Sequence cursor)
                             throws IllegalArgumentException
```
    Throws:
    
    IllegalArgumentException
  - RingBufferConsumerControl
```
protected RingBufferConsumerControl(int sizePowerOfTwo,
                                    RingBufferConsumerControl.ConsumerWaitStrategy waitStrategy,
                                    com.lmax.disruptor.Sequence cursor,
                                    com.lmax.disruptor.util.PaddedLong commonStop)
                             throws IllegalArgumentException
```
    Throws:
    
    IllegalArgumentException
- Method Detail
  - availableTo
```
public long availableTo()
```
    availableTo() is a consumer side call that will block using the wait strategy until a value (or several) have been published. It will return the sequence that represents the position the publisher has published to.
    
    This method can return ACQUIRE_STOP_REQUEST which means the publisher has called RingBufferControl.publishStop(). Once the consumer receives this value the RingBufferControl has been reset.
  - tryAvailableTo
```
public long tryAvailableTo()
```
    This method allows the consumer side to poll for publishing events. It will return what availableTo() will return but can also return UNAVAILABLE which means there's no currently published value available
  - notifyProcessed
```
public void notifyProcessed()
```
    This method must be called by the consumer once the consumer is finished with the currently published results.
  - index
```
public int index(long sequence)
```
    This method will convert the sequence to an index of a ring buffer. ring buffer sold separately.
  - consumeAsIterator
```
public <T> Iterator<T> consumeAsIterator(T[] values)
```
  - consumeAsIterable
```
public <T> Iterable<T> consumeAsIterable(T[] values)
```
  - 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.
  - sumPaddingToPreventOptimisation
```
public long sumPaddingToPreventOptimisation()
```
  - getTail
```
protected com.lmax.disruptor.Sequence getTail()
```
  - clear
```
protected void clear()
```
  - tryAvailableTo
```
protected long tryAvailableTo(long requestedSequence)
```
  - availableTo
```
protected long availableTo(long requestedSequence)
```
  - doNotifyProcessed
```
protected final void doNotifyProcessed(long sequence)
```

Class RingBufferConsumerControl

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

INITIAL_CURSOR_VALUE

ACQUIRE_STOP_REQUEST

UNAVAILABLE

spin

yield

bufferSize

indexMask

waitStrategy

publishCursor

tail

stop

stopIsCommon

p1

p2

p3

p4

p5

p6

iter

Constructor Detail

RingBufferConsumerControl

RingBufferConsumerControl

Method Detail

availableTo

tryAvailableTo

notifyProcessed

index

consumeAsIterator

consumeAsIterable

isShutdown

sumPaddingToPreventOptimisation

getTail

clear

tryAvailableTo

availableTo

doNotifyProcessed