RingBuffer (reactor-core 2.5.0.M4 API)

java.lang.Object
- reactor.core.queue.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, Backpressurable
```
public abstract class RingBuffer<E>
extends java.lang.Object
implements java.util.function.LongSupplier, Backpressurable
```
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 java.util.function.Supplier EMITTED

static long INITIAL_CURSOR_VALUE
Set to -1 as sequence starting point

Fields
Modifier and Type	Field and Description
`static java.util.function.Supplier`	`EMITTED`
`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.
`static <T> java.util.Queue<T>`	`blockingBoundedQueue(RingBuffer<Slot<T>> buffer, long startSequence)` Create a `Queue` view over the given `RingBuffer` of `Slot`.
`static <E> RingBuffer<Slot<E>>`	`createMultiProducer(int bufferSize)` Create a new multiple producer RingBuffer using the default wait strategy `WaitStrategy.busySpin()`.
`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 java.lang.Runnable`	`createRequestTask(org.reactivestreams.Subscription upstream, java.lang.Runnable stopCondition, java.util.function.Consumer<java.lang.Long> postWaitCallback, java.util.function.LongSupplier readCount, WaitStrategy waitStrategy, org.reactivestreams.Subscriber<?> errorSubscriber, int prefetch)` Create a `Runnable` event loop that will keep monitoring a `LongSupplier` and compare it to a `RingBuffer`
`static <E> RingBuffer<Slot<E>>`	`createSingleProducer(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)` 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 Sequence`	`getSequence()` Get the current cursor value for the ring buffer.
`Sequence[]`	`getSequenceReceivers()`
`static int`	`log2(int i)` Calculate the log base 2 of the supplied integer, essentially reports the location of the highest bit.
`abstract RingBufferReceiver`	`newBarrier()` Create a new `RingBufferReceiver` to be used by an EventProcessor 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.
`static <T> java.util.Queue<T>`	`nonBlockingBoundedQueue(RingBuffer<Slot<T>> buffer, long startSequence)` Create a `Queue` view over the given `RingBuffer` of `Slot`.
`static <E> void`	`onNext(E value, RingBuffer<Slot<E>> ringBuffer)` Signal a new `Slot` value to a `RingBuffer` typed with them.
`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.
`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.
`static boolean`	`waitRequestOrTerminalEvent(java.util.function.LongSupplier pendingRequest, RingBufferReceiver barrier, java.util.concurrent.atomic.AtomicBoolean isRunning, java.util.function.LongSupplier nextSequence, java.lang.Runnable waiter)` Spin CPU until the request `LongSupplier` is populated at least once by a strict positive value.
`static Sequence`	`wrap(long init, java.lang.Object delegate)` Wrap a new sequence into a traceable `Producer` thus keeping reference and adding an extra stack level when peeking.
`static Sequence`	`wrap(Sequence init, java.lang.Object delegate)` Wrap a sequence into a traceable `Producer` thus keeping reference and adding an extra stack level when peeking.

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

Methods inherited from interface reactor.core.state.Backpressurable
getCapacity, getPending

- Field Detail
  - EMITTED
```
public static final java.util.function.Supplier EMITTED
```
  - 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
  - createRequestTask
```
public static java.lang.Runnable createRequestTask(org.reactivestreams.Subscription upstream,
                                                   java.lang.Runnable stopCondition,
                                                   java.util.function.Consumer<java.lang.Long> postWaitCallback,
                                                   java.util.function.LongSupplier readCount,
                                                   WaitStrategy waitStrategy,
                                                   org.reactivestreams.Subscriber<?> errorSubscriber,
                                                   int prefetch)
```
    Create a Runnable event loop that will keep monitoring a LongSupplier and compare it to a RingBuffer
    
    Parameters:
    
    upstream - the Subscription to request/cancel on
    
    stopCondition - Runnable evaluated in the spin loop that may throw
    
    postWaitCallback - a Consumer notified with the latest sequence read
    
    readCount - a LongSupplier a sequence cursor to wait on
    
    waitStrategy - a WaitStrategy to trade off cpu cycle for latency
    
    errorSubscriber - an error subscriber if request/cancel fails
    
    prefetch - the target prefetch size
    
    Returns:
    
    a Runnable loop to execute to start the requesting loop
  - createMultiProducer
```
public static <E> RingBuffer<Slot<E>> createMultiProducer(int bufferSize)
```
    Create a new multiple producer RingBuffer using the default wait strategy WaitStrategy.busySpin().
    See MultiProducer.
    
    Type Parameters:
    
    E - the element type
    
    Parameters:
    
    bufferSize - number of elements to create within the ring buffer.
    
    Returns:
    
    the new RingBuffer instance
    
    Throws:
    
    java.lang.IllegalArgumentException - if bufferSize is less than 1 or not a power of 2
  - 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
  - nonBlockingBoundedQueue
```
public static <T> java.util.Queue<T> nonBlockingBoundedQueue(RingBuffer<Slot<T>> buffer,
                                                             long startSequence)
```
    Create a Queue view over the given RingBuffer of Slot. The read cursor will be added to the gating sequences and will be incremented on polling. Offer will return false if the tryNext() does not succeed.
    
    Type Parameters:
    
    T - the Slot data content type
    
    Parameters:
    
    buffer - the RingBuffer repository
    
    startSequence - the starting sequence to track in the Queue
    
    Returns:
    
    a non blocking Queue view of the given RingBuffer
  - blockingBoundedQueue
```
public static <T> java.util.Queue<T> blockingBoundedQueue(RingBuffer<Slot<T>> buffer,
                                                          long startSequence)
```
    Create a Queue view over the given RingBuffer of Slot. The read cursor will be added to the gating sequences and will be incremented on polling. Offer will spin on next() if the ringbuffer is overrun.
    
    Type Parameters:
    
    T - the Slot data content type
    
    Parameters:
    
    buffer - the RingBuffer repository
    
    startSequence - the starting sequence to track in the Queue
    
    Returns:
    
    a non blocking Queue view of the given RingBuffer
  - createSingleProducer
```
public static <E> RingBuffer<Slot<E>> createSingleProducer(int bufferSize)
```
    Create a new single producer RingBuffer using the default wait strategy WaitStrategy.busySpin().
    See MultiProducer.
    
    Type Parameters:
    
    E - the element type
    
    Parameters:
    
    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)
```
    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.
  - 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
  - onNext
```
public static <E> void onNext(E value,
                              RingBuffer<Slot<E>> ringBuffer)
```
    Signal a new Slot value to a RingBuffer typed with them.
    
    Type Parameters:
    
    E - the Slot reified type
    
    Parameters:
    
    value - the data to store
    
    ringBuffer - the target RingBuffer of Slot
  - waitRequestOrTerminalEvent
```
public static boolean waitRequestOrTerminalEvent(java.util.function.LongSupplier pendingRequest,
                                                 RingBufferReceiver barrier,
                                                 java.util.concurrent.atomic.AtomicBoolean isRunning,
                                                 java.util.function.LongSupplier nextSequence,
                                                 java.lang.Runnable waiter)
```
    Spin CPU until the request LongSupplier is populated at least once by a strict positive value. To relieve the spin loop, the read sequence itself will be used against so it will wake up only when a signal is emitted upstream or other stopping condition including terminal signals thrown by the RingBufferReceiver waiting barrier.
    
    Parameters:
    
    pendingRequest - the LongSupplier request to observe
    
    barrier - RingBufferReceiver to wait on
    
    isRunning - AtomicBoolean calling loop running state
    
    nextSequence - LongSupplier ring buffer read cursor
    
    waiter - an optional extra spin observer for the wait strategy in RingBufferReceiver
    
    Returns:
    
    true if a request has been received, false in any other case.
  - wrap
```
public static Sequence wrap(long init,
                            java.lang.Object delegate)
```
    Wrap a new sequence into a traceable Producer thus keeping reference and adding an extra stack level when peeking. Mostly invisible cost but the option is left open. Keeping reference of the arbitrary consumer allows expanded operational navigation (graph) by finding all target subscribers of a given ring buffer.
    
    Parameters:
    
    init - the initial sequence index
    
    delegate - the target to proxy
    
    Returns:
    
    a wrapped Sequence
  - wrap
```
public static Sequence wrap(Sequence init,
                            java.lang.Object delegate)
```
    Wrap a sequence into a traceable Producer thus keeping reference and adding an extra stack level when peeking. Mostly invisible cost but the option is left open.
    
    Parameters:
    
    init - the sequence reference
    
    delegate - the object to wrap
    
    Returns:
    
    a wrapped Sequence
  - 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.
  - 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 RingBufferReceiver.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 RingBufferReceiver.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.
  - 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
  - newBarrier
```
public abstract RingBufferReceiver newBarrier()
```
    Create a new RingBufferReceiver to be used by an EventProcessor 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:
    
    RingBufferReceiver
  - 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 Exceptions.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:
    
    Exceptions.InsufficientCapacityException - if the necessary space in the ring buffer is not available
    
    See Also:
    
    publish(long), get(long)
  - tryNext
```
public abstract long tryNext(int n)
                      throws Exceptions.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:
    
    Exceptions.InsufficientCapacityException - if the necessary space in the ring buffer is not available

Class RingBuffer<E>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface reactor.core.state.Backpressurable

Field Detail

EMITTED

INITIAL_CURSOR_VALUE

Constructor Detail

RingBuffer

Method Detail

createRequestTask

createMultiProducer

createMultiProducer

createMultiProducer

nonBlockingBoundedQueue

blockingBoundedQueue

createSingleProducer

createSingleProducer

createSingleProducer

createSingleProducer

getMinimumSequence

getMinimumSequence

log2

newSequence

onNext

waitRequestOrTerminalEvent

wrap

wrap

addGatingSequence

get

getAsLong

getCursor

getMinimumGatingSequence

getMinimumGatingSequence

getSequence

getSequenceReceivers

newBarrier

next

next

publish

publish

remainingCapacity

removeGatingSequence

resetTo

toString

tryNext

tryNext