Package io.aeron.logbuffer

Class FrameDescriptor

java.lang.Object
io.aeron.logbuffer.FrameDescriptor
public class FrameDescriptor extends Object
Description of the structure for message framing in a log buffer.

All messages are logged in frames that have a minimum header layout as follows plus a reserve then the encoded message follows: 

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |R|                       Frame Length                          |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-------------------------------+
  |  Version      |B|E| Flags     |             Type              |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-------------------------------+
  |R|                       Term Offset                           |
  +-+-------------------------------------------------------------+
  |                      Additional Fields                       ...
 ...                                                              |
  +---------------------------------------------------------------+
  |                        Encoded Message                       ...
 ...                                                              |
  +---------------------------------------------------------------+

The (B)egin and (E)nd flags are used for message fragmentation. R is for reserved bit. Both (B)egin and (E)nd flags are set for a message that does not span frames.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final byte
    BEGIN_FRAG_FLAG
    Beginning fragment of a frame.
    static final byte
    END_FRAG_FLAG
    End fragment of a frame.
    static final int
    FLAGS_OFFSET
    Offset within a frame at which the flags field begins
    static final int
    FRAME_ALIGNMENT
    Alignment as a multiple of bytes for each frame.
    static final int
    MAX_MESSAGE_LENGTH
    Set a pragmatic maximum message length regardless of term length to encourage better design.
    static final int
    PADDING_FRAME_TYPE
    Padding frame type to indicate the message should be ignored.
    static final int
    SESSION_ID_OFFSET
    Offset within a frame at which the session id field begins
    static final int
    TERM_ID_OFFSET
    Offset within a frame at which the term id field begins
    static final int
    TERM_OFFSET
    Offset within a frame at which the term offset field begins
    static final int
    TYPE_OFFSET
    Offset within a frame at which the type field begins
    static final byte
    UNFRAGMENTED
    End fragment of a frame.
    static final int
    VERSION_OFFSET
    Offset within a frame at which the version field begins

  • Constructor Summary

    Constructors
    Constructor
    Description
    FrameDescriptor()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    computeMaxMessageLength(int termLength)
    Compute the maximum supported message length for a buffer of given termLength.
    static int
    flagsOffset(int termOffset)
    The buffer offset at which the flags field begins.
    static byte
    frameFlags(UnsafeBuffer buffer, int termOffset)
    Get the flags field for a frame.
    static void
    frameFlags(UnsafeBuffer buffer, int termOffset, byte flags)
    Write the flags field for a frame.
    static int
    frameLength(UnsafeBuffer buffer, int termOffset)
    Get the length of a frame from the header.
    static void
    frameLengthOrdered(UnsafeBuffer buffer, int termOffset, int frameLength)
    Write the length header for a frame in a memory ordered fashion.
    static int
    frameLengthVolatile(UnsafeBuffer buffer, int termOffset)
    Get the length of a frame from the header as a volatile read.
    static int
    frameSessionId(UnsafeBuffer buffer, int termOffset)
    Get the session id of a frame from the header.
    static void
    frameSessionId(UnsafeBuffer buffer, int termOffset, int sessionId)
    Write the session id field for a frame.
    static int
    frameTermId(UnsafeBuffer buffer, int termOffset)
    Get the term id of a frame from the header.
    static void
    frameTermId(UnsafeBuffer buffer, int termOffset, int termId)
    Write the term id field for a frame.
    static void
    frameTermOffset(UnsafeBuffer buffer, int termOffset)
    Write the term offset field for a frame.
    static int
    frameType(UnsafeBuffer buffer, int termOffset)
    Read the type of the frame from header.
    static void
    frameType(UnsafeBuffer buffer, int termOffset, int type)
    Write the type field for a frame.
    static int
    frameVersion(UnsafeBuffer buffer, int termOffset)
    Read the type of the frame from header.
    static boolean
    isPaddingFrame(UnsafeBuffer buffer, int termOffset)
    Is the frame starting at the termOffset a padding frame at the end of a buffer?
    static int
    lengthOffset(int termOffset)
    The buffer offset at which the length field begins.
    static int
    sessionIdOffset(int termOffset)
    The buffer offset at which the session id field begins.
    static int
    termIdOffset(int termOffset)
    The buffer offset at which the term id field begins.
    static int
    termOffsetOffset(int termOffset)
    The buffer offset at which the term offset field begins.
    static int
    typeOffset(int termOffset)
    The buffer offset at which the type field begins.
    static int
    versionOffset(int termOffset)
    The buffer offset at which the version field begins.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • MAX_MESSAGE_LENGTH

      public static final int MAX_MESSAGE_LENGTH
      Set a pragmatic maximum message length regardless of term length to encourage better design. Messages larger than half the cache size should be broken up into chunks and streamed.
      See Also:

    • FRAME_ALIGNMENT

      public static final int FRAME_ALIGNMENT
      Alignment as a multiple of bytes for each frame. The length field will store the unaligned length in bytes.
      See Also:

    • BEGIN_FRAG_FLAG

      public static final byte BEGIN_FRAG_FLAG
      Beginning fragment of a frame.
      See Also:

    • END_FRAG_FLAG

      public static final byte END_FRAG_FLAG
      End fragment of a frame.
      See Also:

    • UNFRAGMENTED

      public static final byte UNFRAGMENTED
      End fragment of a frame.
      See Also:

    • VERSION_OFFSET

      public static final int VERSION_OFFSET
      Offset within a frame at which the version field begins
      See Also:

    • FLAGS_OFFSET

      public static final int FLAGS_OFFSET
      Offset within a frame at which the flags field begins
      See Also:

    • TYPE_OFFSET

      public static final int TYPE_OFFSET
      Offset within a frame at which the type field begins
      See Also:

    • TERM_OFFSET

      public static final int TERM_OFFSET
      Offset within a frame at which the term offset field begins
      See Also:

    • TERM_ID_OFFSET

      public static final int TERM_ID_OFFSET
      Offset within a frame at which the term id field begins
      See Also:

    • SESSION_ID_OFFSET

      public static final int SESSION_ID_OFFSET
      Offset within a frame at which the session id field begins
      See Also:

    • PADDING_FRAME_TYPE

      public static final int PADDING_FRAME_TYPE
      Padding frame type to indicate the message should be ignored.
      See Also:

  • Constructor Details

    • FrameDescriptor

      public FrameDescriptor()

  • Method Details

    • computeMaxMessageLength

      public static int computeMaxMessageLength(int termLength)
      Compute the maximum supported message length for a buffer of given termLength.
      Parameters:
      termLength - of the log buffer.
      Returns:
      the maximum supported length for a message.

    • lengthOffset

      public static int lengthOffset(int termOffset)
      The buffer offset at which the length field begins.
      Parameters:
      termOffset - at which the frame begins.
      Returns:
      the offset at which the length field begins.

    • versionOffset

      public static int versionOffset(int termOffset)
      The buffer offset at which the version field begins.
      Parameters:
      termOffset - at which the frame begins.
      Returns:
      the offset at which the version field begins.

    • flagsOffset

      public static int flagsOffset(int termOffset)
      The buffer offset at which the flags field begins.
      Parameters:
      termOffset - at which the frame begins.
      Returns:
      the offset at which the flags field begins.

    • typeOffset

      public static int typeOffset(int termOffset)
      The buffer offset at which the type field begins.
      Parameters:
      termOffset - at which the frame begins.
      Returns:
      the offset at which the type field begins.

    • termOffsetOffset

      public static int termOffsetOffset(int termOffset)
      The buffer offset at which the term offset field begins.
      Parameters:
      termOffset - at which the frame begins.
      Returns:
      the offset at which the term offset field begins.

    • termIdOffset

      public static int termIdOffset(int termOffset)
      The buffer offset at which the term id field begins.
      Parameters:
      termOffset - at which the frame begins.
      Returns:
      the offset at which the term id field begins.

    • sessionIdOffset

      public static int sessionIdOffset(int termOffset)
      The buffer offset at which the session id field begins.
      Parameters:
      termOffset - at which the frame begins.
      Returns:
      the offset at which the session id field begins.

    • frameVersion

      public static int frameVersion(UnsafeBuffer buffer, int termOffset)
      Read the type of the frame from header.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      Returns:
      the value of the frame type header.

    • frameFlags

      public static byte frameFlags(UnsafeBuffer buffer, int termOffset)
      Get the flags field for a frame.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      Returns:
      the value of the flags.

    • frameType

      public static int frameType(UnsafeBuffer buffer, int termOffset)
      Read the type of the frame from header.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      Returns:
      the value of the frame type header.

    • isPaddingFrame

      public static boolean isPaddingFrame(UnsafeBuffer buffer, int termOffset)
      Is the frame starting at the termOffset a padding frame at the end of a buffer?
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      Returns:
      true if the frame is a padding frame otherwise false.

    • frameLength

      public static int frameLength(UnsafeBuffer buffer, int termOffset)
      Get the length of a frame from the header.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      Returns:
      the value for the frame length.

    • frameTermId

      public static int frameTermId(UnsafeBuffer buffer, int termOffset)
      Get the term id of a frame from the header.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      Returns:
      the value for the term id field.

    • frameSessionId

      public static int frameSessionId(UnsafeBuffer buffer, int termOffset)
      Get the session id of a frame from the header.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      Returns:
      the value for the session id field.

    • frameLengthVolatile

      public static int frameLengthVolatile(UnsafeBuffer buffer, int termOffset)
      Get the length of a frame from the header as a volatile read.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      Returns:
      the value for the frame length.

    • frameLengthOrdered

      public static void frameLengthOrdered(UnsafeBuffer buffer, int termOffset, int frameLength)
      Write the length header for a frame in a memory ordered fashion.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      frameLength - field to be set for the frame.

    • frameType

      public static void frameType(UnsafeBuffer buffer, int termOffset, int type)
      Write the type field for a frame.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      type - type value for the frame.

    • frameFlags

      public static void frameFlags(UnsafeBuffer buffer, int termOffset, byte flags)
      Write the flags field for a frame.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      flags - value for the frame.

    • frameTermOffset

      public static void frameTermOffset(UnsafeBuffer buffer, int termOffset)
      Write the term offset field for a frame.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.

    • frameTermId

      public static void frameTermId(UnsafeBuffer buffer, int termOffset, int termId)
      Write the term id field for a frame.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      termId - value for the frame.

    • frameSessionId

      public static void frameSessionId(UnsafeBuffer buffer, int termOffset, int sessionId)
      Write the session id field for a frame.
      Parameters:
      buffer - containing the frame.
      termOffset - at which a frame begins.
      sessionId - value for the frame.