Class RingBuffer<E>

    • Field Detail

      • p1

        protected long p1
      • p2

        protected long p2
      • p3

        protected long p3
      • p4

        protected long p4
      • p5

        protected long p5
      • p6

        protected long p6
      • p7

        protected long p7
      • bufferSize

        protected final int bufferSize
      • sequencer

        protected final Sequencer sequencer
    • 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:
        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.
        Parameters:
        factory - used to create the events within the ring buffer.
        bufferSize - number of elements to create within the ring buffer.
        Throws:
        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.
        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:
        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.
        Parameters:
        factory - used to create the events within the ring buffer.
        bufferSize - number of elements to create within the ring buffer.
        Throws:
        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)
        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:
        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
      • resetTo

        @Deprecated
        public void resetTo​(long sequence)
        Deprecated.
        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:
        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 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.
      • 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 - 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 -
        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:
        the size of the RingBuffer.
      • 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 now.
      • 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)
      • 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,​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>
        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,
                                                      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>
        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,
                                                            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>
        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.
      • elementAt

        protected final E elementAt​(long sequence)