com.lmax.disruptor

Class RingBuffer<E>

java.lang.Object

com.lmax.disruptor.RingBuffer<E>

Type Parameters:

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

All Implemented Interfaces:

Cursored, DataProvider<E>

public final class RingBuffer<E>
extends java.lang.Object
implements Cursored, DataProvider<E>

Ring based store of reusable entries containing the data representing an event being exchanged between event producer and EventProcessors.

Field Summary

Fields

Modifier and Type	Field and Description
static long	INITIAL_CURSOR_VALUE

Method Summary

Methods

Modifier and Type	Method and Description
void	addGatingSequences(Sequence... gatingSequences) Add the specified gating sequences to this instance of the Disruptor.
E	claimAndGetPreallocated(long sequence) Sets the cursor to a specific sequence and returns the preallocated entry that is stored there.
static <E> RingBuffer<E>	create(ProducerType producerType, EventFactory<E> factory, int bufferSize, WaitStrategy waitStrategy) Create a new Ring Buffer with the specified producer type (SINGLE or MULTI)
static <E> RingBuffer<E>	createMultiProducer(EventFactory<E> factory, int bufferSize) Create a new multiple producer RingBuffer using the default wait strategy BlockingWaitStrategy.
static <E> RingBuffer<E>	createMultiProducer(EventFactory<E> factory, int bufferSize, WaitStrategy waitStrategy) Create a new multiple producer RingBuffer with the specified wait strategy.
static <E> RingBuffer<E>	createSingleProducer(EventFactory<E> factory, int bufferSize) Create a new single producer RingBuffer using the default wait strategy BlockingWaitStrategy.
static <E> RingBuffer<E>	createSingleProducer(EventFactory<E> factory, int bufferSize, WaitStrategy waitStrategy) Create a new single producer RingBuffer with the specified wait strategy.
int	getBufferSize() The size of the buffer.
long	getCursor() Get the current cursor value for the ring buffer.
long	getMinimumGatingSequence() Get the minimum sequence value from all of the gating sequences added to this ringBuffer.
E	getPreallocated(long sequence) Get the object that is preallocated within the ring buffer.
E	getPublished(long sequence) Get the event for a given sequence in the RingBuffer.
boolean	hasAvailableCapacity(int requiredCapacity) Given specified requiredCapacity determines if that amount of space is available.
boolean	isPublished(long sequence) Determines if a particular entry has been published.
SequenceBarrier	newBarrier(Sequence... sequencesToTrack) Create a new SequenceBarrier 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.
long	next() Increment and return the next sequence for the ring buffer.
void	publish(long sequence) Publish the specified sequence.
void	publishEvent(EventTranslator<E> translator) Publishes an event to the ring buffer.
<A> void	publishEvent(EventTranslatorOneArg<E,A> translator, A arg0) Allows one user supplied argument.
<A,B,C> void	publishEvent(EventTranslatorThreeArg<E,A,B,C> translator, A arg0, B arg1, C arg2) Allows three user supplied arguments
<A,B> void	publishEvent(EventTranslatorTwoArg<E,A,B> translator, A arg0, B arg1) Allows two user supplied arguments.
void	publishEvent(EventTranslatorVararg<E> translator, java.lang.Object... args) Allows a variable number of user supplied arguments
long	remainingCapacity() Get the remaining capacity for this ringBuffer.
boolean	removeGatingSequence(Sequence sequence) Remove the specified sequence from this ringBuffer.
void	resetTo(long sequence) Resets the cursor to a specific value.
long	tryNext() Increment and return the next sequence for the ring buffer.
boolean	tryPublishEvent(EventTranslator<E> translator) Attempts to publish an event to the ring buffer.
<A> boolean	tryPublishEvent(EventTranslatorOneArg<E,A> translator, A arg0) Allows one user supplied argument.
<A,B,C> boolean	tryPublishEvent(EventTranslatorThreeArg<E,A,B,C> translator, A arg0, B arg1, C arg2) Allows three user supplied arguments
<A,B> boolean	tryPublishEvent(EventTranslatorTwoArg<E,A,B> translator, A arg0, B arg1) Allows two user supplied arguments.
boolean	tryPublishEvent(EventTranslatorVararg<E> translator, java.lang.Object... args) Allows a variable number of user supplied arguments

Methods inherited from class java.lang.Object

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

Field Detail

INITIAL_CURSOR_VALUE

public static final long INITIAL_CURSOR_VALUE

See Also:

Constant Field Values

Method Detail

createMultiProducer

public static <E> RingBuffer<E> createMultiProducer(EventFactory<E> factory,
                                    int bufferSize,
                                    WaitStrategy waitStrategy)

Create a new multiple producer RingBuffer with the specified wait strategy.

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.

Throws:

java.lang.IllegalArgumentException - if bufferSize is less than 1 and not a power of 2

See Also:

MultiProducerSequencer

createMultiProducer

public static <E> RingBuffer<E> createMultiProducer(EventFactory<E> factory,
                                    int bufferSize)

Create a new multiple producer RingBuffer using the default wait strategy BlockingWaitStrategy.

Parameters:

factory - used to create the events within the ring buffer.

bufferSize - number of elements to create within the ring buffer.

Throws:

java.lang.IllegalArgumentException - if bufferSize is less than 1 and not a power of 2

See Also:

MultiProducerSequencer

createSingleProducer

public static <E> RingBuffer<E> createSingleProducer(EventFactory<E> factory,
                                     int bufferSize,
                                     WaitStrategy waitStrategy)

Create a new single producer RingBuffer with the specified wait strategy.

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.

Throws:

java.lang.IllegalArgumentException - if bufferSize is less than 1 and not a power of 2

See Also:

SingleProducerSequencer

createSingleProducer

public static <E> RingBuffer<E> createSingleProducer(EventFactory<E> factory,
                                     int bufferSize)

Create a new single producer RingBuffer using the default wait strategy BlockingWaitStrategy.

Parameters:

factory - used to create the events within the ring buffer.

bufferSize - number of elements to create within the ring buffer.

Throws:

java.lang.IllegalArgumentException - if bufferSize is less than 1 and not a power of 2

See Also:

MultiProducerSequencer

create

public static <E> RingBuffer<E> create(ProducerType producerType,
                       EventFactory<E> factory,
                       int bufferSize,
                       WaitStrategy waitStrategy)

Create a new Ring Buffer with the specified producer type (SINGLE or MULTI)

Parameters:

producerType - producer type to use ProducerType.

factory - used to create 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.

Throws:

java.lang.IllegalArgumentException - if bufferSize is less than 1 and not a power of 2

getPublished

public E getPublished(long sequence)

Get the event for a given sequence in the RingBuffer. This method will wait until the value is published before returning. This method should only be used by EventProcessors that are reading values out of the ring buffer. Publishing code should use the getPreallocated(long) call to get a handle onto the preallocated event.

The call implements the appropriate load fence to ensure that the data within the event is visible after this call completes.

Specified by:

getPublished in interface DataProvider<E>

Parameters:

sequence - for the event

Returns:

the event that visibily published by the producer

next

public 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.getPreallocated(sequence);
     // Do some work with the event.
 } finally {
     ringBuffer.publish(sequence);
 }
 

Returns:

The next sequence to publish to.

See Also:

publish(long), getPreallocated(long)

tryNext

public long tryNext()
             throws 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.getPreallocated(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 an InsufficientCapacityException.

Returns:

The next sequence to publish to.

Throws:

InsufficientCapacityException

See Also:

publish(long), getPreallocated(long)

resetTo

public void resetTo(long sequence)

Resets the cursor to a specific value. This can be applied at any time, but it is worth not that it is a racy thing to do 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.

claimAndGetPreallocated

public E claimAndGetPreallocated(long sequence)

Sets the cursor to a specific sequence and returns the preallocated entry that is stored there. This is another deliberatly racy call, that should only be done in controlled circumstances, e.g. initialisation.

Parameters:

sequence - The sequence to claim.

Returns:

The preallocated event.

isPublished

public boolean isPublished(long sequence)

Determines if a particular entry has been published.

Parameters:

sequence - The sequence to identify the entry.

Returns:

If the value has been published or not.

addGatingSequences

public void addGatingSequences(Sequence... gatingSequences)

Add the specified gating sequences to this instance of the Disruptor. They will safely and atomically added to the list of gating sequences.

Parameters:

gatingSequences - The sequences to add.

getMinimumGatingSequence

public 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.

removeGatingSequence

public 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.

newBarrier

public SequenceBarrier newBarrier(Sequence... sequencesToTrack)

Create a new SequenceBarrier 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.

Parameters:

sequencesToTrack -

Returns:

A sequence barrier that will track the specified sequences.

See Also:

SequenceBarrier

getCursor

public final long getCursor()

Get the current cursor value for the ring buffer. The cursor value is the last value that was published, or the highest available sequence that can be consumed.

Specified by:

getCursor in interface Cursored

Returns:

current cursor value

getBufferSize

public int getBufferSize()

The size of the buffer.

hasAvailableCapacity

public boolean hasAvailableCapacity(int requiredCapacity)

Given specified requiredCapacity determines if that amount of space is available. Note, you can not assume that if this method returns true that a call to next() will not block. Especially true if this ring buffer is set up to handle multiple producers.

Parameters:

requiredCapacity - The capacity to check for.

Returns:

true If the specified requiredCapacity is available false if now.

publishEvent

public void publishEvent(EventTranslator<E> translator)

Publishes an event to the ring buffer. It handles claiming the next sequence, getting the current (uninitialised) event from the ring buffer and publishing the claimed sequence after translation.

Parameters:

translator - The user specified translation for the event

tryPublishEvent

public boolean tryPublishEvent(EventTranslator<E> translator)

Attempts to publish an event to the ring buffer. It handles claiming the next sequence, getting the current (uninitialised) event from the ring buffer and publishing the claimed sequence after translation. Will return false if specified capacity was not available.

Parameters:

translator - The user specified translation for the event

Returns:

true if the value was published, false if there was insufficient capacity.

publishEvent

public <A> void publishEvent(EventTranslatorOneArg<E,A> translator,
                    A arg0)

Allows one user supplied argument.

Parameters:

translator - The user specified translation for the event

arg0 - A user supplied argument.

See Also:

publishEvent(EventTranslator)

tryPublishEvent

public <A> boolean tryPublishEvent(EventTranslatorOneArg<E,A> translator,
                          A arg0)

Allows one user supplied argument.

Parameters:

translator - The user specified translation for the event

arg0 - A user supplied argument.

Returns:

true if the value was published, false if there was insufficient capacity.

See Also:

tryPublishEvent(EventTranslator)

publishEvent

public <A,B> void publishEvent(EventTranslatorTwoArg<E,A,B> translator,
                      A arg0,
                      B arg1)

Allows two user supplied arguments.

Parameters:

translator - The user specified translation for the event

arg0 - A user supplied argument.

arg1 - A user supplied argument.

See Also:

publishEvent(EventTranslator)

tryPublishEvent

public <A,B> boolean tryPublishEvent(EventTranslatorTwoArg<E,A,B> translator,
                            A arg0,
                            B arg1)

Allows two user supplied arguments.

Parameters:

translator - The user specified translation for the event

arg0 - A user supplied argument.

arg1 - A user supplied argument.

Returns:

true if the value was published, false if there was insufficient capacity.

See Also:

tryPublishEvent(EventTranslator)

publishEvent

public <A,B,C> void publishEvent(EventTranslatorThreeArg<E,A,B,C> translator,
                        A arg0,
                        B arg1,
                        C arg2)

Allows three user supplied arguments

Parameters:

translator - The user specified translation for the event

arg0 - A user supplied argument.

arg1 - A user supplied argument.

arg2 - A user supplied argument.

See Also:

publishEvent(EventTranslator)

tryPublishEvent

public <A,B,C> boolean tryPublishEvent(EventTranslatorThreeArg<E,A,B,C> translator,
                              A arg0,
                              B arg1,
                              C arg2)

Allows three user supplied arguments

Parameters:

translator - The user specified translation for the event

arg0 - A user supplied argument.

arg1 - A user supplied argument.

arg2 - A user supplied argument.

Returns:

true if the value was published, false if there was insufficient capacity.

See Also:

publishEvent(EventTranslator)

publishEvent

public void publishEvent(EventTranslatorVararg<E> translator,
                java.lang.Object... args)

Allows a variable number of user supplied arguments

Parameters:

translator - The user specified translation for the event

args - User supplied arguments.

See Also:

publishEvent(EventTranslator)

tryPublishEvent

public boolean tryPublishEvent(EventTranslatorVararg<E> translator,
                      java.lang.Object... args)

Allows a variable number of user supplied arguments

Parameters:

translator - The user specified translation for the event

args - User supplied arguments.

Returns:

true if the value was published, false if there was insufficient capacity.

See Also:

publishEvent(EventTranslator)

getPreallocated

public E getPreallocated(long sequence)

Get the object that is preallocated within the ring buffer. This differs from the getPublished(long) \ in that is does not wait until the publisher indicates that object is available. This method should only be used by the publishing thread to get a handle on the preallocated event in order to fill it with data.

Parameters:

sequence - for the event

Returns:

event for the sequence

publish

public 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.

remainingCapacity

public long remainingCapacity()

Get the remaining capacity for this ringBuffer.

Returns:

The number of slots remaining.