/*
 * Copyright 2012 LMAX Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.lmax.disruptor;

Coordinates claiming sequences for access to a data structure while tracking dependent Sequences /**
 * Coordinates claiming sequences for access to a data structure while tracking dependent {@link Sequence}s
 */
public interface Sequencer extends Cursored, Sequenced
{
    
Set to -1 as sequence starting point
/**
     * Set to -1 as sequence starting point
     */
    long INITIAL_CURSOR_VALUE = -1L;

    
Claim a specific sequence.  Only used if initialising the ring buffer to
a specific value.
Params:
sequence – The sequence to initialise too./**
     * Claim a specific sequence.  Only used if initialising the ring buffer to
     * a specific value.
     *
     * @param sequence The sequence to initialise too.
     */
    void claim(long sequence);

    
Confirms if a sequence is published and the event is available for use; non-blocking.
Params:
sequence – of the buffer to check
Returns:
true if the sequence is available for use, false if not/**
     * Confirms if a sequence is published and the event is available for use; non-blocking.
     *
     * @param sequence of the buffer to check
     * @return true if the sequence is available for use, false if not
     */
    boolean isAvailable(long sequence);

    
Add the specified gating sequences to this instance of the Disruptor.  They will
safely and atomically added to the list of gating sequences.
Params:
gatingSequences – The sequences to add./**
     * Add the specified gating sequences to this instance of the Disruptor.  They will
     * safely and atomically added to the list of gating sequences.
     *
     * @param gatingSequences The sequences to add.
     */
    void addGatingSequences(Sequence... gatingSequences);

    
Remove the specified sequence from this sequencer.
Params:
sequence – to be removed.
Returns:
true if this sequence was found, false otherwise./**
     * Remove the specified sequence from this sequencer.
     *
     * @param sequence to be removed.
     * @return <tt>true</tt> if this sequence was found, <tt>false</tt> otherwise.
     */
    boolean removeGatingSequence(Sequence sequence);

    
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.
Params:
sequencesToTrack – All of the sequences that the newly constructed barrier will wait on.
See Also:
SequenceBarrier
Returns:
A sequence barrier that will track the specified sequences./**
     * 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.
     *
     * @param sequencesToTrack All of the sequences that the newly constructed barrier will wait on.
     * @return A sequence barrier that will track the specified sequences.
     * @see SequenceBarrier
     */
    SequenceBarrier newBarrier(Sequence... sequencesToTrack);

    
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./**
     * Get the minimum sequence value from all of the gating sequences
     * added to this ringBuffer.
     *
     * @return The minimum gating sequence or the cursor sequence if
     * no sequences have been added.
     */
    long getMinimumSequence();

    
Get the highest sequence number that can be safely read from the ring buffer.  Depending
on the implementation of the Sequencer this call may need to scan a number of values
in the Sequencer.  The scan will range from nextSequence to availableSequence.  If
there are no available values >= nextSequence the return value will be
nextSequence - 1.  To work correctly a consumer should pass a value that
is 1 higher than the last sequence that was successfully processed.
Params:
nextSequence –      The sequence to start scanning from.
availableSequence – The sequence to scan to.
Returns:
The highest value that can be safely read, will be at least nextSequence - 1./**
     * Get the highest sequence number that can be safely read from the ring buffer.  Depending
     * on the implementation of the Sequencer this call may need to scan a number of values
     * in the Sequencer.  The scan will range from nextSequence to availableSequence.  If
     * there are no available values <code>&gt;= nextSequence</code> the return value will be
     * <code>nextSequence - 1</code>.  To work correctly a consumer should pass a value that
     * is 1 higher than the last sequence that was successfully processed.
     *
     * @param nextSequence      The sequence to start scanning from.
     * @param availableSequence The sequence to scan to.
     * @return The highest value that can be safely read, will be at least <code>nextSequence - 1</code>.
     */
    long getHighestPublishedSequence(long nextSequence, long availableSequence);

    <T> EventPoller<T> newPoller(DataProvider<T> provider, Sequence... gatingSequences);
}