Class MemorySegmentPool

java.lang.Object
express.mvp.roray.utils.memory.MemorySegmentPool
public final class MemorySegmentPool extends Object
A flexible, GC-free, and thread-safe pool for off-heap MemorySegments, designed for use with Loom virtual threads.

This implementation is backed by a Arena.ofShared() and is intended to be used as a long-lived, application-global singleton. It can be safely accessed by any number of virtual threads.

⚠️ WARNING: This component is NOT AutoCloseable. The underlying shared arena is meant to live for the duration of the application.

  • Constructor Details

    • MemorySegmentPool

      public MemorySegmentPool(long segmentSize, int initialSize, int maxSize)
      Creates a pool with default zeroing behavior (enabled).
      Parameters:
      segmentSize - Size of each segment in bytes.
      initialSize - Number of segments to pre-allocate.
      maxSize - Maximum number of segments the pool can create.

    • MemorySegmentPool

      public MemorySegmentPool(long segmentSize, int initialSize, int maxSize, boolean zeroOnRelease)
      Creates a pool with configurable zeroing behavior.
      Parameters:
      segmentSize - Size of each segment in bytes.
      initialSize - Number of segments to pre-allocate.
      maxSize - Maximum number of segments the pool can create.
      zeroOnRelease - Whether to zero segments on release (default: true). Set to false for performance-critical use cases where callers guarantee they will overwrite all data.

  • Method Details

    • acquire

      public MemorySegment acquire()
      Acquires a memory segment from the pool.
      Returns:
      a memory segment of the configured size
      Throws:
      IllegalStateException - if the pool is exhausted

    • acquire

      public MemorySegment acquire(long requiredSize)
      Acquires a memory segment with at least the required size.

      If the required size is less than or equal to the pool's segment size, a pooled segment is returned. Otherwise, a new segment is allocated directly from the arena.

      Parameters:
      requiredSize - the minimum size required
      Returns:
      a memory segment of at least the required size

    • release

      public void release(MemorySegment segment)
      Releases a memory segment back to the pool.

      The segment will be zeroed (if configured) and returned to the pool for reuse. Segments with a different size than the pool's segment size are silently ignored.

      Parameters:
      segment - the segment to release (may be null)

    • getAvailableCount

      public int getAvailableCount()

    • getTotalCount

      public int getTotalCount()

    • getSegmentSize

      public long getSegmentSize()

    • getTotalAllocations

      public long getTotalAllocations()
      Returns the total number of allocations made by this pool since creation. This includes both pooled segments reused and new segments allocated.
      Returns:
      Total allocation count.

    • getCurrentlyInUse

      public int getCurrentlyInUse()
      Returns the current number of segments in use (acquired but not released).
      Returns:
      Currently in-use segment count.

    • getPeakUsage

      public int getPeakUsage()
      Returns the peak number of segments that were in use simultaneously.
      Returns:
      Peak usage count.