Interface BufferRef

All Known Implementing Classes:
BufferRefImpl
public interface BufferRef
A reference-counted handle to a shared off-heap memory segment.

This is a general-purpose building block for off-heap pooling. It wraps a MemorySegment with explicit ownership semantics via reference counting, designed for efficient reuse.

Reference Counting

  • Acquire: When obtained from a pool, refCount starts at 1
  • Retain: Call retain() to increment count when sharing
  • Release: Call release() when done; auto-returns to pool at 0

SoA (Structure of Arrays)

poolIndex() supports SoA patterns where metadata (timestamps, flags, tokens, etc.) is stored in separate primitive arrays indexed by pool index, avoiding additional object overhead.

Thread Safety

Reference counting operations (retain(), release()) are thread-safe using lock-free CAS operations. The underlying segment access is not synchronized; callers must ensure proper happens-before relationships.

See Also:

  • 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 (bytes).
    void
    length(int newLength)
    Sets the length of valid data in the buffer (bytes).
    int
    poolIndex()
    Returns the unique index of this buffer in its pool.
    void
    release()
    Decrements the reference count (auto-returns to pool at 0).
    void
    retain()
    Increments the reference count.
    MemorySegment
    segment()
    Returns the underlying FFM MemorySegment.

  • Method Details

    • segment

      MemorySegment segment()
      Returns the underlying FFM MemorySegment.

      Warning: Accessing this segment after 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.

    • address

      long address()
      Returns the raw native address of the segment.

      This is cached to avoid repeated FFM overhead on hot paths.

    • poolIndex

      int poolIndex()
      Returns the unique index of this buffer in its pool.
      Returns:
      pool index (0-based)

    • length

      int length()
      Returns the current length of valid data in the buffer (bytes).

    • length

      void length(int newLength)
      Sets the length of valid data in the buffer (bytes).

    • retain

      void retain()
      Increments the reference count.

    • release

      void release()
      Decrements the reference count (auto-returns to pool at 0).