Class BufferRefImpl

java.lang.Object
express.mvp.myra.transport.buffer.BufferRefImpl
All Implemented Interfaces:
BufferRef
public final class BufferRefImpl extends Object implements BufferRef
Lock-free implementation of BufferRef with atomic reference counting.

This implementation uses VarHandle for lock-free CAS operations on the reference count, providing thread-safe retain/release without blocking.

Memory Layout

  • segment: Immutable reference to off-heap memory
  • address: Cached native address for fast access
  • poolIndex: Index in the parent pool's buffer array
  • registrationId: io_uring buffer registration ID
  • refCount: Atomic reference count (volatile int)
  • length: Current valid data length (mutable)

Reference Count States

  • 0: Buffer is in pool (available for acquisition)
  • 1: Buffer is acquired by one owner
  • >1: Buffer is shared across multiple owners

Thread Safety

retain() and release() use CAS loops for lock-free atomic updates. The length field is not synchronized and should only be modified by the current owner.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    BufferRefImpl(MemorySegment segment, int poolIndex, short registrationId, IntConsumer releaseAction)
    Creates a new buffer reference.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    address()
    Returns the raw native address of the segment.
    int
    length()
    Returns the current length of valid data in the buffer.
    void
    length(int newLength)
    Sets the length of valid data in the buffer.
    int
    poolIndex()
    Returns the unique index of this buffer in the global pool.
    short
    registrationId()
    Returns the io_uring registration ID if registered.
    void
    release()
    Decrements the reference count.
    void
    reset()
    Resets the buffer for reuse after acquisition from pool.
    void
    retain()
    Increments the reference count.
    MemorySegment
    segment()
    Returns the underlying FFM MemorySegment.
    String
    toString()
     

    Methods inherited from class Object

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

  • Constructor Details

    • BufferRefImpl

      public BufferRefImpl(MemorySegment segment, int poolIndex, short registrationId, IntConsumer releaseAction)
      Creates a new buffer reference.

      Initially created with refCount=0 (in pool state). Call reset() when acquiring from pool.

      Parameters:
      segment - the memory segment backing this buffer
      poolIndex - the buffer's index in the pool
      registrationId - the io_uring registration ID
      releaseAction - callback to return buffer to pool

  • Method Details

    • reset

      public void reset()
      Resets the buffer for reuse after acquisition from pool.

      Note: Should only be called by the pool during acquire. Sets refCount to 1 and length to 0. Uses CAS to ensure the buffer was actually in the pool (refCount=0).

      Throws:
      IllegalStateException - if refCount was not 0 (indicates a bug)

    • segment

      public MemorySegment segment()
      Description copied from interface: BufferRef
      Returns the underlying FFM MemorySegment.

      Warning: Accessing this segment after BufferRef.release() has reduced the refCount to 0 is undefined behavior. The segment may be reused by another thread or the underlying memory may be invalidated.

      Specified by:
      segment in interface BufferRef
      Returns:
      the memory segment backing this buffer

    • address

      public long address()
      Description copied from interface: BufferRef
      Returns the raw native address of the segment.

      This is cached to avoid JNI/FFM overhead on hot paths. Useful for direct native library integration.

      Specified by:
      address in interface BufferRef
      Returns:
      the native memory address

    • poolIndex

      public int poolIndex()
      Description copied from interface: BufferRef
      Returns the unique index of this buffer in the global pool.

      This enables "Structure of Arrays" (SoA) patterns where metadata (refCounts, timestamps, operation tokens) is stored in separate primitive arrays indexed by this ID, rather than in object fields.

      Specified by:
      poolIndex in interface BufferRef
      Returns:
      the buffer's index in its pool (0-based)

    • registrationId

      public short registrationId()
      Description copied from interface: BufferRef
      Returns the io_uring registration ID if registered.

      For io_uring backends, this is the buffer index used with IORING_OP_READ_FIXED and IORING_OP_WRITE_FIXED.

      Specified by:
      registrationId in interface BufferRef
      Returns:
      the registration ID, or -1 if not registered

    • length

      public int length()
      Description copied from interface: BufferRef
      Returns the current length of valid data in the buffer.

      This represents the actual payload size (e.g., packet length), not the buffer capacity.

      Specified by:
      length in interface BufferRef
      Returns:
      the valid data length in bytes

    • length

      public void length(int newLength)
      Description copied from interface: BufferRef
      Sets the length of valid data in the buffer.
      Specified by:
      length in interface BufferRef
      Parameters:
      newLength - the new data length in bytes

    • retain

      public void retain()
      Description copied from interface: BufferRef
      Increments the reference count.

      Must be called before sharing the buffer with another thread or holding it asynchronously past the current scope.

      Specified by:
      retain in interface BufferRef

    • release

      public void release()
      Description copied from interface: BufferRef
      Decrements the reference count.

      If the count reaches 0, the buffer is automatically returned to its pool for reuse. After the final release, the buffer must not be accessed.

      Specified by:
      release in interface BufferRef

    • toString

      public String toString()
      Overrides:
      toString in class Object