Package org.agrona

Class ExpandableRingBuffer

java.lang.Object
org.agrona.ExpandableRingBuffer
public class ExpandableRingBuffer extends Object
Ring-buffer for storing messages which can expand to accommodate the messages written into it. Message are written and read in a FIFO order with capacity up to maxCapacity(). Messages can be iterated via for-each methods without consuming and having the option to begin iteration an offset from the current head() position.

Note: This class is not thread safe.

  • Field Details

    • MAX_CAPACITY

      public static final int MAX_CAPACITY
      Maximum capacity to which the ring buffer can grow which is 1 GB.
      See Also:

    • HEADER_ALIGNMENT

      public static final int HEADER_ALIGNMENT
      Alignment in bytes for the beginning of message header.
      See Also:

    • HEADER_LENGTH

      public static final int HEADER_LENGTH
      Length of encapsulating header.
      See Also:

  • Constructor Details

    • ExpandableRingBuffer

      public ExpandableRingBuffer()
      Create a new ring buffer which is initially compact and empty, has potential for MAX_CAPACITY, and using a direct ByteBuffer.

    • ExpandableRingBuffer

      public ExpandableRingBuffer(int initialCapacity, int maxCapacity, boolean isDirect)
      Create a new ring buffer providing configuration for initial and max capacity, plus whether it is direct or not.
      Parameters:
      initialCapacity - required in the buffer.
      maxCapacity - the buffer can expand to.
      isDirect - is the ByteBuffer allocated direct or heap based.

  • Method Details

    • isDirect

      public boolean isDirect()
      Is the ByteBuffer used for backing storage direct, that is off Java heap, or not.
      Returns:
      return true if direct ByteBuffer or false for heap based ByteBuffer.

    • maxCapacity

      public int maxCapacity()
      The maximum capacity to which the buffer can expand.
      Returns:
      maximum capacity to which the buffer can expand.

    • capacity

      public int capacity()
      Current capacity of the ring buffer in bytes.
      Returns:
      the current capacity of the ring buffer in bytes.

    • size

      public int size()
      Size of the ring buffer currently populated in bytes.
      Returns:
      size of the ring buffer currently populated in bytes.

    • isEmpty

      public boolean isEmpty()
      Is the ring buffer currently empty.
      Returns:
      true if the ring buffer is empty otherwise false.

    • head

      public long head()
      Head position in the buffer from which bytes are consumed forward toward the tail().
      Returns:
      head position in the buffer from which bytes are consumed forward towards the tail().
      See Also:

    • tail

      public long tail()
      Tail position in the buffer at which new bytes are appended.
      Returns:
      tail position in the buffer at which new bytes are appended.
      See Also:

    • reset

      public void reset(int requiredCapacity)
      Reset the buffer with a new capacity and empty state. Buffer capacity will grow or shrink as necessary.
      Parameters:
      requiredCapacity - for the ring buffer. If the same as exiting capacity then no adjustment is made.

    • forEach

      public int forEach(ExpandableRingBuffer.MessageConsumer messageConsumer, int limit)
      Iterate encoded contents and pass messages to the ExpandableRingBuffer.MessageConsumer which can stop by returning false.
      Parameters:
      messageConsumer - to which the encoded messages are passed.
      limit - for the number of entries to iterate over.
      Returns:
      count of bytes iterated.
      See Also:

    • forEach

      public int forEach(int headOffset, ExpandableRingBuffer.MessageConsumer messageConsumer, int limit)
      Iterate encoded contents and pass messages to the ExpandableRingBuffer.MessageConsumer which can stop by returning false.
      Parameters:
      headOffset - offset from head which must be <= tail(), and be the start a message.
      messageConsumer - to which the encoded messages are passed.
      limit - for the number of entries to iterate over.
      Returns:
      count of bytes iterated.
      See Also:

    • consume

      public int consume(ExpandableRingBuffer.MessageConsumer messageConsumer, int messageLimit)
      Consume messages up to a limit and pass them to the ExpandableRingBuffer.MessageConsumer.
      Parameters:
      messageConsumer - to which the encoded messages are passed.
      messageLimit - on the number of messages to consume per read operation.
      Returns:
      the number of bytes consumed
      See Also:

    • append

      public boolean append(DirectBuffer srcBuffer, int srcOffset, int srcLength)
      Append a message into the ring buffer, expanding the buffer if required.
      Parameters:
      srcBuffer - containing the encoded message.
      srcOffset - within the buffer at which the message begins.
      srcLength - of the encoded message in the buffer.
      Returns:
      true if successful otherwise false if maxCapacity() is reached.