Module java.base
Package java.lang.foreignPREVIEW

Interface SegmentAllocator

All Known Subinterfaces:
ArenaPREVIEW
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface SegmentAllocator
SegmentAllocator is a preview API of the Java platform.
Programs can only use SegmentAllocator when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
An object that may be used to allocate memory segmentsPREVIEW. Clients implementing this interface must implement the allocate(long, long) method. A segment allocator defines several methods which can be useful to create segments from several kinds of Java values such as primitives and arrays.

SegmentAllocator is a functional interface. Clients can easily obtain a new segment allocator by using either a lambda expression or a method reference: 

SegmentAllocator autoAllocator = (byteSize, byteAlignment) -> Arena.ofAuto().allocate(byteSize, byteAlignment);

This interface defines factories for commonly used allocators:

Passing a segment allocator to an API can be especially useful in circumstances where a client wants to communicate where the results of a certain operation (performed by the API) should be stored, as a memory segment. For instance, downcall method handlesPREVIEW can accept an additional SegmentAllocatorPREVIEW parameter if the underlying foreign function is known to return a struct by-value. Effectively, the allocator parameter tells the linker where to store the return value of the foreign function.

API Note:
Unless otherwise specified, the allocate(long, long) method is not thread-safe. Furthermore, memory segments allocated by a segment allocator can be associated with different lifetimes, and can even be backed by overlapping regions of memory. For these reasons, clients should generally only interact with a segment allocator they own.

Clients should consider using an arenaPREVIEW instead, which, provides strong thread-safety, lifetime and non-overlapping guarantees.

Since:
19

  • Method Details

    • allocateUtf8String

      default MemorySegmentPREVIEW allocateUtf8String(String str)
      Returns a new memory segment with a Java string converted into a UTF-8 encoded, null-terminated C string.

      This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement byte array. The CharsetEncoder class should be used when more control over the encoding process is required.

      If the given string contains any '\0' characters, they will be copied as well. This means that, depending on the method used to read the string, such as MemorySegment.getUtf8String(long)PREVIEW, the string will appear truncated when read again.

      Implementation Requirements:
      The default implementation for this method copies the contents of the provided Java string into a new memory segment obtained by calling this.allocate(str.length() + 1).
      Parameters:
      str - the Java string to be converted into a C string.
      Returns:
      a new memory segment with a Java string converted into a UTF-8 encoded, null-terminated C string

    • allocate

      default MemorySegmentPREVIEW allocate(ValueLayout.OfBytePREVIEW layout, byte value)
      Returns a new memory segment initialized with the provided byte value as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      Parameters:
      layout - the layout of the block of memory to be allocated.
      value - the value to be set in the newly allocated memory segment.
      Returns:
      a new memory segment initialized with the provided byte value as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocate

      default MemorySegmentPREVIEW allocate(ValueLayout.OfCharPREVIEW layout, char value)
      Returns a new memory segment initialized with the provided char value as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      Parameters:
      layout - the layout of the block of memory to be allocated.
      value - the value to be set in the newly allocated memory segment.
      Returns:
      a new memory segment initialized with the provided char value as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocate

      default MemorySegmentPREVIEW allocate(ValueLayout.OfShortPREVIEW layout, short value)
      Returns a new memory segment initialized with the provided short value as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      Parameters:
      layout - the layout of the block of memory to be allocated.
      value - the value to be set in the newly allocated memory segment.
      Returns:
      a new memory segment initialized with the provided short value as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocate

      default MemorySegmentPREVIEW allocate(ValueLayout.OfIntPREVIEW layout, int value)
      Returns a new memory segment initialized with the provided int value as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      Parameters:
      layout - the layout of the block of memory to be allocated.
      value - the value to be set in the newly allocated memory segment.
      Returns:
      a new memory segment initialized with the provided int value as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocate

      default MemorySegmentPREVIEW allocate(ValueLayout.OfFloatPREVIEW layout, float value)
      Returns a new memory segment initialized with the provided float value as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      Parameters:
      layout - the layout of the block of memory to be allocated.
      value - the value to be set in the newly allocated memory segment.
      Returns:
      a new memory segment initialized with the provided float value as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocate

      default MemorySegmentPREVIEW allocate(ValueLayout.OfLongPREVIEW layout, long value)
      Returns a new memory segment initialized with the provided long value as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      Parameters:
      layout - the layout of the block of memory to be allocated.
      value - the value to be set in the newly allocated memory segment.
      Returns:
      a new memory segment initialized with the provided long value as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocate

      default MemorySegmentPREVIEW allocate(ValueLayout.OfDoublePREVIEW layout, double value)
      Returns a new memory segment initialized with the provided double value as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      Parameters:
      layout - the layout of the block of memory to be allocated.
      value - the value to be set in the newly allocated memory segment.
      Returns:
      a new memory segment initialized with the provided double value as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocate

      default MemorySegmentPREVIEW allocate(AddressLayoutPREVIEW layout, MemorySegmentPREVIEW value)
      Returns a new memory segment initialized with the address of the provided value as specified by the provided layout (i.e. byte ordering, alignment and size).

      The address value might be narrowed according to the platform address size (see ValueLayout.ADDRESSPREVIEW).

      Implementation Requirements:
      The default implementation is equivalent to: 
       Objects.requireNonNull(value);
 MemorySegment seg = allocate(Objects.requireNonNull(layout));
 seg.set(layout, 0, value);
 return seg;
      Parameters:
      layout - the layout of the block of memory to be allocated.
      value - the value to be set in the newly allocated memory segment.
      Returns:
      a new memory segment initialized with the address of the provided value as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocateArray

      default MemorySegmentPREVIEW allocateArray(ValueLayout.OfBytePREVIEW elementLayout, byte... elements)
      Returns a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E byte elements as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       int size = Objects.requireNonNull(elements).length;
 MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size);
 MemorySegment.copy(elements, 0, seg, elementLayout, 0, size);
 return seg;
      Parameters:
      elementLayout - the element layout of the array to be allocated.
      elements - the short elements to be copied to the newly allocated memory block.
      Returns:
      a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E byte elements as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocateArray

      default MemorySegmentPREVIEW allocateArray(ValueLayout.OfShortPREVIEW elementLayout, short... elements)
      Returns a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E short elements as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       int size = Objects.requireNonNull(elements).length;
 MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size);
 MemorySegment.copy(elements, 0, seg, elementLayout, 0, size);
 return seg;
      Parameters:
      elementLayout - the element layout of the array to be allocated.
      elements - the short elements to be copied to the newly allocated memory block.
      Returns:
      a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E short elements as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocateArray

      default MemorySegmentPREVIEW allocateArray(ValueLayout.OfCharPREVIEW elementLayout, char... elements)
      Returns a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E char elements as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       int size = Objects.requireNonNull(elements).length;
 MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size);
 MemorySegment.copy(elements, 0, seg, elementLayout, 0, size);
 return seg;
      Parameters:
      elementLayout - the element layout of the array to be allocated.
      elements - the short elements to be copied to the newly allocated memory block.
      Returns:
      a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E char elements as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocateArray

      default MemorySegmentPREVIEW allocateArray(ValueLayout.OfIntPREVIEW elementLayout, int... elements)
      Returns a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E int elements as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       int size = Objects.requireNonNull(elements).length;
 MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size);
 MemorySegment.copy(elements, 0, seg, elementLayout, 0, size);
 return seg;
      Parameters:
      elementLayout - the element layout of the array to be allocated.
      elements - the short elements to be copied to the newly allocated memory block.
      Returns:
      a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E int elements as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocateArray

      default MemorySegmentPREVIEW allocateArray(ValueLayout.OfFloatPREVIEW elementLayout, float... elements)
      Returns a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E float elements as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       int size = Objects.requireNonNull(elements).length;
 MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size);
 MemorySegment.copy(elements, 0, seg, elementLayout, 0, size);
 return seg;
      Parameters:
      elementLayout - the element layout of the array to be allocated.
      elements - the short elements to be copied to the newly allocated memory block.
      Returns:
      a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E float elements as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocateArray

      default MemorySegmentPREVIEW allocateArray(ValueLayout.OfLongPREVIEW elementLayout, long... elements)
      Returns a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E long elements as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       int size = Objects.requireNonNull(elements).length;
 MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size);
 MemorySegment.copy(elements, 0, seg, elementLayout, 0, size);
 return seg;
      Parameters:
      elementLayout - the element layout of the array to be allocated.
      elements - the short elements to be copied to the newly allocated memory block.
      Returns:
      a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E long elements as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocateArray

      default MemorySegmentPREVIEW allocateArray(ValueLayout.OfDoublePREVIEW elementLayout, double... elements)
      Returns a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E double elements as specified by the provided layout (i.e. byte ordering, alignment and size).
      Implementation Requirements:
      The default implementation is equivalent to: 
       int size = Objects.requireNonNull(elements).length;
 MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size);
 MemorySegment.copy(elements, 0, seg, elementLayout, 0, size);
 return seg;
      Parameters:
      elementLayout - the element layout of the array to be allocated.
      elements - the short elements to be copied to the newly allocated memory block.
      Returns:
      a new memory segment with a byteSize()PREVIEW of E*layout.byteSize() initialized with the provided E double elements as specified by the provided layout (i.e. byte ordering, alignment and size)

    • allocate

      default MemorySegmentPREVIEW allocate(MemoryLayoutPREVIEW layout)
      Returns a new memory segment with the given layout.
      Implementation Requirements:
      The default implementation for this method calls this.allocate(layout.byteSize(), layout.byteAlignment()).
      Parameters:
      layout - the layout of the block of memory to be allocated.
      Returns:
      a new memory segment with the given layout

    • allocateArray

      default MemorySegmentPREVIEW allocateArray(MemoryLayoutPREVIEW elementLayout, long count)
      Returns a new memory segment with the given elementLayout and count.
      Implementation Requirements:
      The default implementation for this method calls this.allocate(MemoryLayout.sequenceLayout(count, elementLayout)).
      Parameters:
      elementLayout - the array element layout.
      count - the array element count.
      Returns:
      a new memory segment with the given elementLayout and count
      Throws:
      IllegalArgumentException - if elementLayout.byteSize() * count overflows.
      IllegalArgumentException - if count < 0.

    • allocate

      default MemorySegmentPREVIEW allocate(long byteSize)
      Returns a new memory segment with the given byteSize.
      Implementation Requirements:
      The default implementation for this method calls this.allocate(byteSize, 1).
      Parameters:
      byteSize - the size (in bytes) of the block of memory to be allocated.
      Returns:
      a new memory segment with the given byteSize
      Throws:
      IllegalArgumentException - if byteSize < 0

    • allocate

      MemorySegmentPREVIEW allocate(long byteSize, long byteAlignment)
      Returns a new memory segment with the given byteSize and byteAlignment.
      Parameters:
      byteSize - the size (in bytes) of the block of memory to be allocated.
      byteAlignment - the alignment (in bytes) of the block of memory to be allocated.
      Returns:
      a new memory segment with the given byteSize and byteAlignment
      Throws:
      IllegalArgumentException - if byteSize < 0, byteAlignment <= 0, or if byteAlignment is not a power of 2.

    • slicingAllocator

      static SegmentAllocatorPREVIEW slicingAllocator(MemorySegmentPREVIEW segment)
      Returns a segment allocator which responds to allocation requests by returning consecutive slices obtained from the provided segment. Each new allocation request will return a new slice starting at the current offset (modulo additional padding to satisfy alignment constraint), with given size.

      The returned allocator throws IndexOutOfBoundsException when a slice of the provided segment with the requested size and alignment cannot be found.

      Implementation Note:
      A slicing allocator is not thread-safe.
      Parameters:
      segment - the segment which the returned allocator should slice from.
      Returns:
      a new slicing allocator

    • prefixAllocator

      static SegmentAllocatorPREVIEW prefixAllocator(MemorySegmentPREVIEW segment)
      Returns a segment allocator which responds to allocation requests by recycling a single segment. Each new allocation request will return a new slice starting at the segment offset 0, hence the name prefix allocator. Equivalent to (but likely more efficient than) the following code: 
      MemorySegment segment = ...
SegmentAllocator prefixAllocator = (size, align) -> segment.asSlice(0, size, align);
      The returned allocator throws IndexOutOfBoundsException when a slice of the provided segment with the requested size and alignment cannot be found.
      API Note:
      A prefix allocator can be useful to limit allocation requests in case a client knows that they have fully processed the contents of the allocated segment before the subsequent allocation request takes place.
      Implementation Note:
      While a prefix allocator is thread-safe, concurrent access on the same recycling allocator might cause a thread to overwrite contents written to the underlying segment by a different thread.
      Parameters:
      segment - the memory segment to be recycled by the returned allocator.
      Returns:
      an allocator which recycles an existing segment upon each new allocation request.