Module com.lmax.disruptor
Package com.lmax.disruptor

Class RingBuffer<E>

    • Field Detail

      • INITIAL_CURSOR_VALUE

        public static final long INITIAL_CURSOR_VALUE
        The 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.
        Type Parameters:
        E - Class of the event stored in the ring buffer.
        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:
        a constructed ring buffer.
        Throws:
        java.lang.IllegalArgumentException - if bufferSize is less than 1 or 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.
        Type Parameters:
        E - Class of the event stored in the ring buffer.
        Parameters:
        factory - used to create the events within the ring buffer.
        bufferSize - number of elements to create within the ring buffer.
        Returns:
        a constructed ring buffer.
        Throws:
        java.lang.IllegalArgumentException - if bufferSize is less than 1 or 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.
        Type Parameters:
        E - Class of the event stored in the ring buffer.
        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:
        a constructed ring buffer.
        Throws:
        java.lang.IllegalArgumentException - if bufferSize is less than 1 or 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.
        Type Parameters:
        E - Class of the event stored in the ring buffer.
        Parameters:
        factory - used to create the events within the ring buffer.
        bufferSize - number of elements to create within the ring buffer.
        Returns:
        a constructed ring buffer.
        Throws:
        java.lang.IllegalArgumentException - if bufferSize is less than 1 or 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)
        Type Parameters:
        E - Class of the event stored in the ring buffer.
        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.
        Returns:
        a constructed ring buffer.
        Throws:
        java.lang.IllegalArgumentException - if bufferSize is less than 1 or not a power of 2

      • get

        public 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 SequenceBarrier.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 SequenceBarrier.waitFor(long) method.

        Specified by:
        get in interface DataProvider<E>
        Parameters:
        sequence - for the event
        Returns:
        the event for the given sequence

      • 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.get(sequence);
     // Do some work with the event.
 } finally {
     ringBuffer.publish(sequence);
 }
        Specified by:
        next in interface Sequenced
        Returns:
        The next sequence to publish to.
        See Also:
        publish(long), get(long)

      • next

        public long next​(int n)
        The same functionality as next(), but allows the caller to claim the next n sequences.
        Specified by:
        next in interface Sequenced
        Parameters:
        n - number of slots to claim
        Returns:
        sequence number of the highest slot claimed
        See Also:
        Sequenced.next(int)

      • 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.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 an InsufficientCapacityException.

        Specified by:
        tryNext in interface Sequenced
        Returns:
        The next sequence to publish to.
        Throws:
        InsufficientCapacityException - if the necessary space in the ring buffer is not available
        See Also:
        publish(long), get(long)

      • tryNext

        public long tryNext​(int n)
             throws InsufficientCapacityException
        The same functionality as tryNext(), but allows the caller to attempt to claim the next n sequences.
        Specified by:
        tryNext in interface Sequenced
        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

      • claimAndGetPreallocated

        public E claimAndGetPreallocated​(long sequence)
        Sets the cursor to a specific sequence and returns the preallocated entry that is stored there. This can cause a data race and should only be done in controlled circumstances, e.g. during initialisation.
        Parameters:
        sequence - The sequence to claim.
        Returns:
        The preallocated event.

      • isAvailable

        public boolean isAvailable​(long sequence)
        Determines if the event for a given sequence is currently available.

        Note that this does not guarantee that event will still be available on the next interaction with the RingBuffer. For example, it is not necessarily safe to write code like this: 

        
 if (ringBuffer.isAvailable(sequence))
 {
     final E e = ringBuffer.get(sequence);
     // ...do something with e
 }

        because there is a race between the reading thread and the writing thread.

        This method will also return false when querying for sequences that are behind the ring buffer's wrap point.

        Parameters:
        sequence - The sequence to identify the entry.
        Returns:
        If the event published with the given sequence number is currently available.

      • 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 - the additional sequences to track
        Returns:
        A sequence barrier that will track the specified sequences.
        See Also:
        SequenceBarrier

      • newPoller

        public EventPoller<E> newPoller​(Sequence... gatingSequences)
        Creates an event poller for this ring buffer gated on the supplied sequences.
        Parameters:
        gatingSequences - to be gated on.
        Returns:
        A poller that will gate on this ring buffer and the supplied sequences.

      • getBufferSize

        public int getBufferSize()
        The size of the buffer.
        Specified by:
        getBufferSize in interface Sequenced
        Returns:
        size of 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.
        Specified by:
        hasAvailableCapacity in interface Sequenced
        Parameters:
        requiredCapacity - The capacity to check for.
        Returns:
        true If the specified requiredCapacity is available false if not.

      • tryPublishEvent

        public boolean tryPublishEvent​(EventTranslator<E> translator)
        Description copied from interface: EventSink
        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.
        Specified by:
        tryPublishEvent in interface EventSink<E>
        Parameters:
        translator - The user specified translation for the event
        Returns:
        true if the value was published, false if there was insufficient capacity.
        See Also:
        EventSink.tryPublishEvent(com.lmax.disruptor.EventTranslator)

      • tryPublishEvent

        public <A,​B,​C> boolean tryPublishEvent​(EventTranslatorThreeArg<E,​A,​B,​C> translator,
                                                   A arg0,
                                                   B arg1,
                                                   C arg2)
        Description copied from interface: EventSink
        Allows three user supplied arguments
        Specified by:
        tryPublishEvent in interface EventSink<E>
        Type Parameters:
        A - Class of the user supplied argument
        B - Class of the user supplied argument
        C - Class of the user supplied argument
        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:
        com.lmax.disruptor.EventSink#tryPublishEvent(com.lmax.disruptor.EventTranslatorThreeArg, A, B, C)

      • publishEvents

        public void publishEvents​(EventTranslator<E>[] translators)
        Description copied from interface: EventSink

        Publishes multiple events 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.

        With this call the data that is to be inserted into the ring buffer will be a field (either explicitly or captured anonymously), therefore this call will require an instance of the translator for each value that is to be inserted into the ring buffer.

        Specified by:
        publishEvents in interface EventSink<E>
        Parameters:
        translators - The user specified translation for each event
        See Also:
        EventSink.publishEvents(com.lmax.disruptor.EventTranslator[])

      • publishEvents

        public void publishEvents​(EventTranslator<E>[] translators,
                          int batchStartsAt,
                          int batchSize)
        Description copied from interface: EventSink

        Publishes multiple events 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.

        With this call the data that is to be inserted into the ring buffer will be a field (either explicitly or captured anonymously), therefore this call will require an instance of the translator for each value that is to be inserted into the ring buffer.

        Specified by:
        publishEvents in interface EventSink<E>
        Parameters:
        translators - The user specified translation for each event
        batchStartsAt - The first element of the array which is within the batch.
        batchSize - The actual size of the batch
        See Also:
        EventSink.publishEvents(com.lmax.disruptor.EventTranslator[], int, int)

      • tryPublishEvents

        public boolean tryPublishEvents​(EventTranslator<E>[] translators)
        Description copied from interface: EventSink
        Attempts to publish multiple events 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.
        Specified by:
        tryPublishEvents in interface EventSink<E>
        Parameters:
        translators - The user specified translation for the event
        Returns:
        true if the value was published, false if there was insufficient capacity.
        See Also:
        EventSink.tryPublishEvents(com.lmax.disruptor.EventTranslator[])

      • tryPublishEvents

        public boolean tryPublishEvents​(EventTranslator<E>[] translators,
                                int batchStartsAt,
                                int batchSize)
        Description copied from interface: EventSink
        Attempts to publish multiple events 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.
        Specified by:
        tryPublishEvents in interface EventSink<E>
        Parameters:
        translators - The user specified translation for the event
        batchStartsAt - The first element of the array which is within the batch.
        batchSize - The actual size of the batch
        Returns:
        true if all the values were published, false if there was insufficient capacity.
        See Also:
        EventSink.tryPublishEvents(com.lmax.disruptor.EventTranslator[], int, int)

      • tryPublishEvents

        public <A> boolean tryPublishEvents​(EventTranslatorOneArg<E,​A> translator,
                                    int batchStartsAt,
                                    int batchSize,
                                    A[] arg0)
        Description copied from interface: EventSink
        Allows one user supplied argument.
        Specified by:
        tryPublishEvents in interface EventSink<E>
        Type Parameters:
        A - Class of the user supplied argument
        Parameters:
        translator - The user specified translation for each event
        batchStartsAt - The first element of the array which is within the batch.
        batchSize - The actual size of the batch
        arg0 - An array of user supplied arguments, one element per event.
        Returns:
        true if the value was published, false if there was insufficient capacity.
        See Also:
        com.lmax.disruptor.EventSink#tryPublishEvents(com.lmax.disruptor.EventTranslatorOneArg, int, int, A[])

      • publishEvents

        public <A,​B> void publishEvents​(EventTranslatorTwoArg<E,​A,​B> translator,
                                      int batchStartsAt,
                                      int batchSize,
                                      A[] arg0,
                                      B[] arg1)
        Description copied from interface: EventSink
        Allows two user supplied arguments per event.
        Specified by:
        publishEvents in interface EventSink<E>
        Type Parameters:
        A - Class of the user supplied argument
        B - Class of the user supplied argument
        Parameters:
        translator - The user specified translation for the event
        batchStartsAt - The first element of the array which is within the batch.
        batchSize - The actual size of the batch.
        arg0 - An array of user supplied arguments, one element per event.
        arg1 - An array of user supplied arguments, one element per event.
        See Also:
        com.lmax.disruptor.EventSink#publishEvents(com.lmax.disruptor.EventTranslatorTwoArg, int, int, A[], B[])

      • tryPublishEvents

        public <A,​B> boolean tryPublishEvents​(EventTranslatorTwoArg<E,​A,​B> translator,
                                            A[] arg0,
                                            B[] arg1)
        Description copied from interface: EventSink
        Allows two user supplied arguments per event.
        Specified by:
        tryPublishEvents in interface EventSink<E>
        Type Parameters:
        A - Class of the user supplied argument
        B - Class of the user supplied argument
        Parameters:
        translator - The user specified translation for the event
        arg0 - An array of user supplied arguments, one element per event.
        arg1 - An array of user supplied arguments, one element per event.
        Returns:
        true if the value was published, false if there was insufficient capacity.
        See Also:
        com.lmax.disruptor.EventSink#tryPublishEvents(com.lmax.disruptor.EventTranslatorTwoArg, A[], B[])

      • tryPublishEvents

        public <A,​B> boolean tryPublishEvents​(EventTranslatorTwoArg<E,​A,​B> translator,
                                            int batchStartsAt,
                                            int batchSize,
                                            A[] arg0,
                                            B[] arg1)
        Description copied from interface: EventSink
        Allows two user supplied arguments per event.
        Specified by:
        tryPublishEvents in interface EventSink<E>
        Type Parameters:
        A - Class of the user supplied argument
        B - Class of the user supplied argument
        Parameters:
        translator - The user specified translation for the event
        batchStartsAt - The first element of the array which is within the batch.
        batchSize - The actual size of the batch.
        arg0 - An array of user supplied arguments, one element per event.
        arg1 - An array of user supplied arguments, one element per event.
        Returns:
        true if the value was published, false if there was insufficient capacity.
        See Also:
        com.lmax.disruptor.EventSink#tryPublishEvents(com.lmax.disruptor.EventTranslatorTwoArg, int, int, A[], B[])

      • publishEvents

        public <A,​B,​C> void publishEvents​(EventTranslatorThreeArg<E,​A,​B,​C> translator,
                                              A[] arg0,
                                              B[] arg1,
                                              C[] arg2)
        Description copied from interface: EventSink
        Allows three user supplied arguments per event.
        Specified by:
        publishEvents in interface EventSink<E>
        Type Parameters:
        A - Class of the user supplied argument
        B - Class of the user supplied argument
        C - Class of the user supplied argument
        Parameters:
        translator - The user specified translation for the event
        arg0 - An array of user supplied arguments, one element per event.
        arg1 - An array of user supplied arguments, one element per event.
        arg2 - An array of user supplied arguments, one element per event.
        See Also:
        com.lmax.disruptor.EventSink#publishEvents(com.lmax.disruptor.EventTranslatorThreeArg, A[], B[], C[])

      • publishEvents

        public <A,​B,​C> void publishEvents​(EventTranslatorThreeArg<E,​A,​B,​C> translator,
                                              int batchStartsAt,
                                              int batchSize,
                                              A[] arg0,
                                              B[] arg1,
                                              C[] arg2)
        Description copied from interface: EventSink
        Allows three user supplied arguments per event.
        Specified by:
        publishEvents in interface EventSink<E>
        Type Parameters:
        A - Class of the user supplied argument
        B - Class of the user supplied argument
        C - Class of the user supplied argument
        Parameters:
        translator - The user specified translation for the event
        batchStartsAt - The first element of the array which is within the batch.
        batchSize - The number of elements in the batch.
        arg0 - An array of user supplied arguments, one element per event.
        arg1 - An array of user supplied arguments, one element per event.
        arg2 - An array of user supplied arguments, one element per event.
        See Also:
        com.lmax.disruptor.EventSink#publishEvents(com.lmax.disruptor.EventTranslatorThreeArg, int, int, A[], B[], C[])

      • tryPublishEvents

        public <A,​B,​C> boolean tryPublishEvents​(EventTranslatorThreeArg<E,​A,​B,​C> translator,
                                                    A[] arg0,
                                                    B[] arg1,
                                                    C[] arg2)
        Description copied from interface: EventSink
        Allows three user supplied arguments per event.
        Specified by:
        tryPublishEvents in interface EventSink<E>
        Type Parameters:
        A - Class of the user supplied argument
        B - Class of the user supplied argument
        C - Class of the user supplied argument
        Parameters:
        translator - The user specified translation for the event
        arg0 - An array of user supplied arguments, one element per event.
        arg1 - An array of user supplied arguments, one element per event.
        arg2 - An array of user supplied arguments, one element per event.
        Returns:
        true if the value was published, false if there was insufficient capacity.
        See Also:
        com.lmax.disruptor.EventSink#tryPublishEvents(com.lmax.disruptor.EventTranslatorThreeArg, A[], B[], C[])

      • tryPublishEvents

        public <A,​B,​C> boolean tryPublishEvents​(EventTranslatorThreeArg<E,​A,​B,​C> translator,
                                                    int batchStartsAt,
                                                    int batchSize,
                                                    A[] arg0,
                                                    B[] arg1,
                                                    C[] arg2)
        Description copied from interface: EventSink
        Allows three user supplied arguments per event.
        Specified by:
        tryPublishEvents in interface EventSink<E>
        Type Parameters:
        A - Class of the user supplied argument
        B - Class of the user supplied argument
        C - Class of the user supplied argument
        Parameters:
        translator - The user specified translation for the event
        batchStartsAt - The first element of the array which is within the batch.
        batchSize - The actual size of the batch.
        arg0 - An array of user supplied arguments, one element per event.
        arg1 - An array of user supplied arguments, one element per event.
        arg2 - An array of user supplied arguments, one element per event.
        Returns:
        true if the value was published, false if there was insufficient capacity.
        See Also:
        com.lmax.disruptor.EventSink#tryPublishEvents(com.lmax.disruptor.EventTranslatorThreeArg, int, int, A[], B[], C[])

      • publish

        public void publish​(long sequence)
        Publish the specified sequence. This action marks this particular message as being available to be read.
        Specified by:
        publish in interface Sequenced
        Parameters:
        sequence - the sequence to publish.

      • publish

        public void publish​(long lo,
                    long hi)
        Publish the specified sequences. This action marks these particular messages as being available to be read.
        Specified by:
        publish in interface Sequenced
        Parameters:
        lo - the lowest sequence number to be published
        hi - the highest sequence number to be published
        See Also:
        Sequenced.next(int)

      • remainingCapacity

        public long remainingCapacity()
        Get the remaining capacity for this ringBuffer.
        Specified by:
        remainingCapacity in interface Sequenced
        Returns:
        The number of slots remaining.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object