RingBuffer (reactor-core 3.0.0.RC1 API)

java.lang.Object
- reactor.util.concurrent.RingBuffer<E>

Type Parameters:

E - implementation storing the data for sharing during exchange or parallel coordination of an event.

All Implemented Interfaces:

java.util.function.LongSupplier
```
public abstract class RingBuffer<E>
extends java.lang.Object
implements java.util.function.LongSupplier
```
Ring based store of reusable entries containing the data representing an event being exchanged between event producer and ringbuffer consumers.

Field Summary

Fields
Modifier and Type Field and Description

static long INITIAL_CURSOR_VALUE
Set to -1 as sequence starting point

Fields
Modifier and Type	Field and Description
`static long`	`INITIAL_CURSOR_VALUE` Set to -1 as sequence starting point

Constructor Summary

Constructors
Constructor and Description

RingBuffer()

Constructors
Constructor and Description
`RingBuffer()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract void`	`addGatingSequence(Sequence gatingSequence)` Add the specified gating sequence to this instance of the Disruptor.
`abstract int`	`bufferSize()`
`static <E> RingBuffer<E>`	`createMultiProducer(java.util.function.Supplier<E> factory, int bufferSize, WaitStrategy waitStrategy)` Create a new multiple producer RingBuffer with the specified wait strategy.
`static <E> RingBuffer<E>`	`createMultiProducer(java.util.function.Supplier<E> factory, int bufferSize, WaitStrategy waitStrategy, java.lang.Runnable spinObserver)` Create a new multiple producer RingBuffer with the specified wait strategy.
`static <E> RingBuffer<E>`	`createSingleProducer(java.util.function.Supplier<E> factory, int bufferSize)` Create a new single producer RingBuffer using the default wait strategy `WaitStrategy.busySpin()`.
`static <E> RingBuffer<E>`	`createSingleProducer(java.util.function.Supplier<E> factory, int bufferSize, WaitStrategy waitStrategy)` Create a new single producer RingBuffer with the specified wait strategy.
`static <E> RingBuffer<E>`	`createSingleProducer(java.util.function.Supplier<E> factory, int bufferSize, WaitStrategy waitStrategy, java.lang.Runnable spinObserver)` Create a new single producer RingBuffer with the specified wait strategy.
`abstract E`	`get(long sequence)` Get the event for a given sequence in the RingBuffer.
`long`	`getAsLong()`
`abstract long`	`getCursor()` Get the current cursor value for the ring buffer.
`abstract long`	`getMinimumGatingSequence()` Get the minimum sequence value from all of the gating sequences added to this ringBuffer.
`abstract long`	`getMinimumGatingSequence(Sequence sequence)` Get the minimum sequence value from all of the gating sequences added to this ringBuffer.
`static long`	`getMinimumSequence(Sequence[] sequences, long minimum)` Get the minimum sequence from an array of `Sequence`s.
`static long`	`getMinimumSequence(Sequence excludeSequence, Sequence[] sequences, long minimum)` Get the minimum sequence from an array of `Sequence`s.
`abstract int`	`getPending()` Get the buffered count
`abstract Sequence`	`getSequence()` Get the current cursor value for the ring buffer.
`Sequence[]`	`getSequenceReceivers()`
`static boolean`	`isAlert(java.lang.Throwable t)` Test if exception is alert
`static int`	`log2(int i)` Calculate the log base 2 of the supplied integer, essentially reports the location of the highest bit.
`abstract RingBufferReader`	`newReader()` Create a new `RingBufferReader` to track which messages are available to be read from the ring buffer given a list of sequences to track.
`static Sequence`	`newSequence(long init)`
`abstract long`	`next()` Increment and return the next sequence for the ring buffer.
`abstract long`	`next(int n)` The same functionality as `next()`, but allows the caller to claim the next n sequences.
`abstract void`	`publish(long sequence)` Publish the specified sequence.
`abstract void`	`publish(long lo, long hi)` Publish the specified sequences.
`abstract long`	`remainingCapacity()` Get the remaining capacity for this ringBuffer.
`abstract boolean`	`removeGatingSequence(Sequence sequence)` Remove the specified sequence from this ringBuffer.
`abstract void`	`resetTo(long sequence)` Resets the cursor to a specific value.
`static void`	`throwAlert()` Throw a signal singleton exception that can be checked against `isAlert(Throwable)`
`java.lang.String`	`toString()`
`abstract long`	`tryNext()` Increment and return the next sequence for the ring buffer.
`abstract long`	`tryNext(int n)` The same functionality as `tryNext()`, but allows the caller to attempt to claim the next n sequences.

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

- Field Detail
  - INITIAL_CURSOR_VALUE
```
public static final long INITIAL_CURSOR_VALUE
```
    Set to -1 as sequence starting point
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - RingBuffer
```
public RingBuffer()
```
- Method Detail
  - createMultiProducer
```
public static <E> RingBuffer<E> createMultiProducer(java.util.function.Supplier<E> factory,
                                                    int bufferSize,
                                                    WaitStrategy waitStrategy)
```
    Create a new multiple producer RingBuffer with the specified wait strategy.
    See MultiProducer.
    
    Type Parameters:
    
    E - the element type
    
    Parameters:
    
    factory - used to create the events within the ring buffer.
    
    bufferSize - number of elements to create within the ring buffer.
    
    waitStrategy - used to determine how to wait for new elements to become available.
    
    Returns:
    
    the new RingBuffer instance
  - createMultiProducer
```
public static <E> RingBuffer<E> createMultiProducer(java.util.function.Supplier<E> factory,
                                                    int bufferSize,
                                                    WaitStrategy waitStrategy,
                                                    java.lang.Runnable spinObserver)
```
    Create a new multiple producer RingBuffer with the specified wait strategy.
    See MultiProducer.
    
    Type Parameters:
    
    E - the element type
    
    Parameters:
    
    factory - used to create the events within the ring buffer.
    
    bufferSize - number of elements to create within the ring buffer.
    
    waitStrategy - used to determine how to wait for new elements to become available.
    
    spinObserver - the Runnable to call on a spin loop wait
    
    Returns:
    
    the new RingBuffer instance
  - createSingleProducer
```
public static <E> RingBuffer<E> createSingleProducer(java.util.function.Supplier<E> factory,
                                                     int bufferSize)
```
    Create a new single producer RingBuffer using the default wait strategy WaitStrategy.busySpin().
    See MultiProducer.
    
    Type Parameters:
    
    E - the element type
    
    Parameters:
    
    factory - used to create the events within the ring buffer.
    
    bufferSize - number of elements to create within the ring buffer.
    
    Returns:
    
    the new RingBuffer instance
  - createSingleProducer
```
public static <E> RingBuffer<E> createSingleProducer(java.util.function.Supplier<E> factory,
                                                     int bufferSize,
                                                     WaitStrategy waitStrategy)
```
    Create a new single producer RingBuffer with the specified wait strategy.
    See MultiProducer.
    
    Type Parameters:
    
    E - the element type
    
    Parameters:
    
    factory - used to create the events within the ring buffer.
    
    bufferSize - number of elements to create within the ring buffer.
    
    waitStrategy - used to determine how to wait for new elements to become available.
    
    Returns:
    
    the new RingBuffer instance
  - createSingleProducer
```
public static <E> RingBuffer<E> createSingleProducer(java.util.function.Supplier<E> factory,
                                                     int bufferSize,
                                                     WaitStrategy waitStrategy,
                                                     java.lang.Runnable spinObserver)
```
    Create a new single producer RingBuffer with the specified wait strategy.
    See MultiProducer.
    
    Type Parameters:
    
    E - the element type
    
    Parameters:
    
    factory - used to create the events within the ring buffer.
    
    bufferSize - number of elements to create within the ring buffer.
    
    waitStrategy - used to determine how to wait for new elements to become available.
    
    spinObserver - called each time the next claim is spinning and waiting for a slot
    
    Returns:
    
    the new RingBuffer instance
  - getMinimumSequence
```
public static long getMinimumSequence(Sequence[] sequences,
                                      long minimum)
```
    Get the minimum sequence from an array of Sequences.
    
    Parameters:
    
    sequences - to compare.
    
    minimum - an initial default minimum. If the array is empty this value will be returned.
    
    Returns:
    
    the minimum sequence found or Long.MAX_VALUE if the array is empty.
  - getMinimumSequence
```
public static long getMinimumSequence(Sequence excludeSequence,
                                      Sequence[] sequences,
                                      long minimum)
```
    Get the minimum sequence from an array of Sequences.
    
    Parameters:
    
    excludeSequence - to exclude from search.
    
    sequences - to compare.
    
    minimum - an initial default minimum. If the array is empty this value will be returned.
    
    Returns:
    
    the minimum sequence found or Long.MAX_VALUE if the array is empty.
  - isAlert
```
public static boolean isAlert(java.lang.Throwable t)
```
    Test if exception is alert
    
    Parameters:
    
    t - exception checked
    
    Returns:
    
    true if this is an alert signal
  - log2
```
public static int log2(int i)
```
    Calculate the log base 2 of the supplied integer, essentially reports the location of the highest bit.
    
    Parameters:
    
    i - Value to calculate log2 for.
    
    Returns:
    
    The log2 value
  - newSequence
```
public static Sequence newSequence(long init)
```
    Parameters:
    
    init - the initial value
    
    Returns:
    
    a safe or unsafe sequence set to the passed init value
  - throwAlert
```
public static void throwAlert()
```
    Throw a signal singleton exception that can be checked against isAlert(Throwable)
  - addGatingSequence
```
public abstract void addGatingSequence(Sequence gatingSequence)
```
    Add the specified gating sequence to this instance of the Disruptor. It will safely and atomically be added to the list of gating sequences and not RESET to the current ringbuffer cursor.
    
    Parameters:
    
    gatingSequence - The sequences to add.
  - bufferSize
```
public abstract int bufferSize()
```
    Returns:
    
    the fixed buffer size
  - get
```
public abstract E get(long sequence)
```
    Get the event for a given sequence in the RingBuffer.
    
    This call has 2 uses. Firstly use this call when publishing to a ring buffer. After calling next() use this call to get hold of the preallocated event to fill with data before calling publish(long).
    
    Secondly use this call when consuming data from the ring buffer. After calling RingBufferReader.waitFor(long) call this method with any value greater than that your current consumer sequence and less than or equal to the value returned from the RingBufferReader.waitFor(long) method.
    
    Parameters:
    
    sequence - for the event
    
    Returns:
    
    the event for the given sequence
  - getAsLong
```
public long getAsLong()
```
    Specified by:
    
    getAsLong in interface java.util.function.LongSupplier
  - getCursor
```
public abstract long getCursor()
```
    Get the current cursor value for the ring buffer. The actual value recieved will depend on the type of RingBufferProducer that is being used.
    See MultiProducer. See SingleProducerSequencer
    
    Returns:
    
    the current cursor value
  - getMinimumGatingSequence
```
public abstract long getMinimumGatingSequence()
```
    Get the minimum sequence value from all of the gating sequences added to this ringBuffer.
    
    Returns:
    
    The minimum gating sequence or the cursor sequence if no sequences have been added.
  - getMinimumGatingSequence
```
public abstract long getMinimumGatingSequence(Sequence sequence)
```
    Get the minimum sequence value from all of the gating sequences added to this ringBuffer.
    
    Parameters:
    
    sequence - the target sequence
    
    Returns:
    
    The minimum gating sequence or the cursor sequence if no sequences have been added.
  - getPending
```
public abstract int getPending()
```
    Get the buffered count
    
    Returns:
    
    the buffered count
  - getSequence
```
public abstract Sequence getSequence()
```
    Get the current cursor value for the ring buffer. The actual value recieved will depend on the type of RingBufferProducer that is being used.
    See MultiProducer. See SingleProducerSequencer.
    
    Returns:
    
    the current cursor sequence
  - getSequenceReceivers
```
public Sequence[] getSequenceReceivers()
```
    Returns:
    
    the current list of read cursors
  - newReader
```
public abstract RingBufferReader newReader()
```
    Create a new RingBufferReader to track which messages are available to be read from the ring buffer given a list of sequences to track.
    
    Returns:
    
    A sequence barrier that will track the ringbuffer.
    
    See Also:
    
    RingBufferReader
  - next
```
public abstract long next()
```
    Increment and return the next sequence for the ring buffer. Calls of this method should ensure that they always publish the sequence afterward. E.g.
```
 long sequence = ringBuffer.next();
 try {
     Event e = ringBuffer.get(sequence);
     // Do some work with the event.
 } finally {
     ringBuffer.publish(sequence);
 }
 
```
    Returns:
    
    The next sequence to publish to.
    
    See Also:
    
    publish(long), get(long)
  - next
```
public abstract long next(int n)
```
    The same functionality as next(), but allows the caller to claim the next n sequences.
    See RingBufferProducer.next(int)
    
    Parameters:
    
    n - number of slots to claim
    
    Returns:
    
    sequence number of the highest slot claimed
  - publish
```
public abstract void publish(long sequence)
```
    Publish the specified sequence. This action marks this particular message as being available to be read.
    
    Parameters:
    
    sequence - the sequence to publish.
  - publish
```
public abstract void publish(long lo,
                             long hi)
```
    Publish the specified sequences. This action marks these particular messages as being available to be read.
    See RingBufferProducer.next(int)
    
    Parameters:
    
    lo - the lowest sequence number to be published
    
    hi - the highest sequence number to be published
  - remainingCapacity
```
public abstract long remainingCapacity()
```
    Get the remaining capacity for this ringBuffer.
    
    Returns:
    
    The number of slots remaining.
  - removeGatingSequence
```
public abstract boolean removeGatingSequence(Sequence sequence)
```
    Remove the specified sequence from this ringBuffer.
    
    Parameters:
    
    sequence - to be removed.
    
    Returns:
    
    true if this sequence was found, false otherwise.
  - resetTo
```
public abstract void resetTo(long sequence)
```
    Resets the cursor to a specific value. This can be applied at any time, but it is worth noting that it can cause a data race and should only be used in controlled circumstances. E.g. during initialisation.
    
    Parameters:
    
    sequence - The sequence to reset too.
    
    Throws:
    
    java.lang.IllegalStateException - If any gating sequences have already been specified.
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - tryNext
```
public abstract long tryNext()
                      throws reactor.util.concurrent.RingBuffer.InsufficientCapacityException
```
    Increment and return the next sequence for the ring buffer. Calls of this method should ensure that they always publish the sequence afterward. E.g.
```
 long sequence = ringBuffer.next();
 try {
     Event e = ringBuffer.get(sequence);
     // Do some work with the event.
 } finally {
     ringBuffer.publish(sequence);
 }
 
```
    This method will not block if there is not space available in the ring buffer, instead it will throw a RuntimeException.
    Returns:
    
    The next sequence to publish to.
    
    Throws:
    
    InsufficientCapacityException - if the necessary space in the ring buffer is not available
    
    reactor.util.concurrent.RingBuffer.InsufficientCapacityException
    
    See Also:
    
    publish(long), get(long)
  - tryNext
```
public abstract long tryNext(int n)
                      throws reactor.util.concurrent.RingBuffer.InsufficientCapacityException
```
    The same functionality as tryNext(), but allows the caller to attempt to claim the next n sequences.
    
    Parameters:
    
    n - number of slots to claim
    
    Returns:
    
    sequence number of the highest slot claimed
    
    Throws:
    
    InsufficientCapacityException - if the necessary space in the ring buffer is not available
    
    reactor.util.concurrent.RingBuffer.InsufficientCapacityException

Class RingBuffer<E>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

INITIAL_CURSOR_VALUE

Constructor Detail

RingBuffer

Method Detail

createMultiProducer

createMultiProducer

createSingleProducer

createSingleProducer

createSingleProducer

getMinimumSequence

getMinimumSequence

isAlert

log2

newSequence

throwAlert

addGatingSequence

bufferSize

get

getAsLong

getCursor

getMinimumGatingSequence

getMinimumGatingSequence

getPending

getSequence

getSequenceReceivers

newReader

next

next

publish

publish

remainingCapacity

removeGatingSequence

resetTo

toString

tryNext

tryNext