package com.lmax.disruptor;

public interface Sequenced
{
    
The capacity of the data structure to hold entries.
Returns:
the size of the RingBuffer./**
     * The capacity of the data structure to hold entries.
     *
     * @return the size of the RingBuffer.
     */
    int getBufferSize();

    
Has the buffer got capacity to allocate another sequence.  This is a concurrent
method so the response should only be taken as an indication of available capacity.
Params:
requiredCapacity – in the buffer
Returns:
true if the buffer has the capacity to allocate the next sequence otherwise false./**
     * Has the buffer got capacity to allocate another sequence.  This is a concurrent
     * method so the response should only be taken as an indication of available capacity.
     *
     * @param requiredCapacity in the buffer
     * @return true if the buffer has the capacity to allocate the next sequence otherwise false.
     */
    boolean hasAvailableCapacity(int requiredCapacity);

    
Get the remaining capacity for this sequencer.
Returns:
The number of slots remaining./**
     * Get the remaining capacity for this sequencer.
     *
     * @return The number of slots remaining.
     */
    long remainingCapacity();

    
Claim the next event in sequence for publishing.
Returns:
the claimed sequence value/**
     * Claim the next event in sequence for publishing.
     *
     * @return the claimed sequence value
     */
    long next();

    
Claim the next n events in sequence for publishing.  This is for batch event producing.  Using batch producing
requires a little care and some math.
int n = 10;
long hi = sequencer.next(n);
long lo = hi - (n - 1);
for (long sequence = lo; sequence <= hi; sequence++) {
    // Do work.
}
sequencer.publish(lo, hi);

Params:
n – the number of sequences to claim
Returns:
the highest claimed sequence value/**
     * Claim the next n events in sequence for publishing.  This is for batch event producing.  Using batch producing
     * requires a little care and some math.
     * <pre>
     * int n = 10;
     * long hi = sequencer.next(n);
     * long lo = hi - (n - 1);
     * for (long sequence = lo; sequence &lt;= hi; sequence++) {
     *     // Do work.
     * }
     * sequencer.publish(lo, hi);
     * </pre>
     *
     * @param n the number of sequences to claim
     * @return the highest claimed sequence value
     */
    long next(int n);

    
Attempt to claim the next event in sequence for publishing.  Will return the
number of the slot if there is at least requiredCapacity slots
available.
Throws:
InsufficientCapacityException – thrown if there is no space available in the ring buffer.
Returns:
the claimed sequence value/**
     * Attempt to claim the next event in sequence for publishing.  Will return the
     * number of the slot if there is at least <code>requiredCapacity</code> slots
     * available.
     *
     * @return the claimed sequence value
     * @throws InsufficientCapacityException thrown if there is no space available in the ring buffer.
     */
    long tryNext() throws InsufficientCapacityException;

    
Attempt to claim the next n events in sequence for publishing.  Will return the
highest numbered slot if there is at least requiredCapacity slots available. Have a look at next() for a description on how to use this method. 
Params:
n – the number of sequences to claim
Throws:
InsufficientCapacityException – thrown if there is no space available in the ring buffer.
Returns:
the claimed sequence value/**
     * Attempt to claim the next n events in sequence for publishing.  Will return the
     * highest numbered slot if there is at least <code>requiredCapacity</code> slots
     * available.  Have a look at {@link Sequencer#next()} for a description on how to
     * use this method.
     *
     * @param n the number of sequences to claim
     * @return the claimed sequence value
     * @throws InsufficientCapacityException thrown if there is no space available in the ring buffer.
     */
    long tryNext(int n) throws InsufficientCapacityException;

    
Publishes a sequence. Call when the event has been filled.
Params:
sequence – the sequence to be published./**
     * Publishes a sequence. Call when the event has been filled.
     *
     * @param sequence the sequence to be published.
     */
    void publish(long sequence);

    
Batch publish sequences.  Called when all of the events have been filled.
Params:
lo – first sequence number to publish
hi – last sequence number to publish/**
     * Batch publish sequences.  Called when all of the events have been filled.
     *
     * @param lo first sequence number to publish
     * @param hi last sequence number to publish
     */
    void publish(long lo, long hi);
}