@FunctionalInterface public interface SegmentAllocator
SegmentAllocator
is a preview API of the Java platform. 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:
slicingAllocator(MemorySegment)
obtains an efficient slicing allocator, where memory is allocated by repeatedly slicing the provided memory segment;prefixAllocator(MemorySegment)
obtains an allocator which wraps a segment and recycles its content upon each new allocation request. 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 SegmentAllocator
PREVIEW 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.
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.
Modifier and Type | Method | Description |
---|---|---|
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given size. |
MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given size and alignment constraint. |
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given layout and initializes it with the given address value. |
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given layout. |
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given layout and initializes it with the given byte value. |
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given layout and initializes it with the given char value. |
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given layout and initializes it with the given double value. |
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given layout and initializes it with the given float value. |
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given layout and initializes it with the given int value. |
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given layout and initializes it with the given long value. |
default MemorySegmentPREVIEW |
allocate |
Allocates a memory segment with the given layout and initializes it with the given short value. |
default MemorySegmentPREVIEW |
allocateArray |
Allocates a memory segment with the given element layout and size. |
default MemorySegmentPREVIEW |
allocateArray |
Allocates a memory segment with the given layout and initializes it with the given byte elements. |
default MemorySegmentPREVIEW |
allocateArray |
Allocates a memory segment with the given layout and initializes it with the given char elements. |
default MemorySegmentPREVIEW |
allocateArray |
Allocates a memory segment with the given layout and initializes it with the given double elements. |
default MemorySegmentPREVIEW |
allocateArray |
Allocates a memory segment with the given layout and initializes it with the given float elements. |
default MemorySegmentPREVIEW |
allocateArray |
Allocates a memory segment with the given layout and initializes it with the given int elements. |
default MemorySegmentPREVIEW |
allocateArray |
Allocates a memory segment with the given layout and initializes it with the given long elements. |
default MemorySegmentPREVIEW |
allocateArray |
Allocates a memory segment with the given layout and initializes it with the given short elements. |
default MemorySegmentPREVIEW |
allocateUtf8String |
Converts a Java string into a UTF-8 encoded, null-terminated C string, storing the result into a memory segment. |
static SegmentAllocatorPREVIEW |
prefixAllocator |
Returns a segment allocator which responds to allocation requests by recycling a single segment. |
static SegmentAllocatorPREVIEW |
slicingAllocator |
Returns a segment allocator which responds to allocation requests by returning consecutive slices obtained from the provided segment. |
default MemorySegmentPREVIEW allocateUtf8String(String str)
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.
this.allocate(str.length() + 1)
.str
- the Java string to be converted into a C string.default MemorySegmentPREVIEW allocate(ValueLayout.OfBytePREVIEW layout, byte value)
this.allocate(layout)
.layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.default MemorySegmentPREVIEW allocate(ValueLayout.OfCharPREVIEW layout, char value)
this.allocate(layout)
.layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.default MemorySegmentPREVIEW allocate(ValueLayout.OfShortPREVIEW layout, short value)
this.allocate(layout)
.layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.default MemorySegmentPREVIEW allocate(ValueLayout.OfIntPREVIEW layout, int value)
this.allocate(layout)
.layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.default MemorySegmentPREVIEW allocate(ValueLayout.OfFloatPREVIEW layout, float value)
this.allocate(layout)
.layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.default MemorySegmentPREVIEW allocate(ValueLayout.OfLongPREVIEW layout, long value)
this.allocate(layout)
.layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.default MemorySegmentPREVIEW allocate(ValueLayout.OfDoublePREVIEW layout, double value)
this.allocate(layout)
.layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.default MemorySegmentPREVIEW allocate(AddressLayoutPREVIEW layout, MemorySegmentPREVIEW value)
ValueLayout.ADDRESS
PREVIEW).this.allocate(layout)
.layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.default MemorySegmentPREVIEW allocateArray(ValueLayout.OfBytePREVIEW elementLayout, byte... elements)
this.allocateArray(layout, array.length)
.elementLayout
- the element layout of the array to be allocated.elements
- the byte elements to be copied to the newly allocated memory block.default MemorySegmentPREVIEW allocateArray(ValueLayout.OfShortPREVIEW elementLayout, short... elements)
this.allocateArray(layout, array.length)
.elementLayout
- the element layout of the array to be allocated.elements
- the short elements to be copied to the newly allocated memory block.default MemorySegmentPREVIEW allocateArray(ValueLayout.OfCharPREVIEW elementLayout, char... elements)
this.allocateArray(layout, array.length)
.elementLayout
- the element layout of the array to be allocated.elements
- the char elements to be copied to the newly allocated memory block.default MemorySegmentPREVIEW allocateArray(ValueLayout.OfIntPREVIEW elementLayout, int... elements)
this.allocateArray(layout, array.length)
.elementLayout
- the element layout of the array to be allocated.elements
- the int elements to be copied to the newly allocated memory block.default MemorySegmentPREVIEW allocateArray(ValueLayout.OfFloatPREVIEW elementLayout, float... elements)
this.allocateArray(layout, array.length)
.elementLayout
- the element layout of the array to be allocated.elements
- the float elements to be copied to the newly allocated memory block.default MemorySegmentPREVIEW allocateArray(ValueLayout.OfLongPREVIEW elementLayout, long... elements)
this.allocateArray(layout, array.length)
.elementLayout
- the element layout of the array to be allocated.elements
- the long elements to be copied to the newly allocated memory block.default MemorySegmentPREVIEW allocateArray(ValueLayout.OfDoublePREVIEW elementLayout, double... elements)
this.allocateArray(layout, array.length)
.elementLayout
- the element layout of the array to be allocated.elements
- the double elements to be copied to the newly allocated memory block.default MemorySegmentPREVIEW allocate(MemoryLayoutPREVIEW layout)
this.allocate(layout.byteSize(), layout.byteAlignment())
.layout
- the layout of the block of memory to be allocated.default MemorySegmentPREVIEW allocateArray(MemoryLayoutPREVIEW elementLayout, long count)
this.allocate(MemoryLayout.sequenceLayout(count, elementLayout))
.elementLayout
- the array element layout.count
- the array element count.IllegalArgumentException
- if elementLayout.byteSize() * count
overflows.IllegalArgumentException
- if count < 0
.default MemorySegmentPREVIEW allocate(long byteSize)
this.allocate(byteSize, 1)
.byteSize
- the size (in bytes) of the block of memory to be allocated.IllegalArgumentException
- if byteSize < 0
MemorySegmentPREVIEW allocate(long byteSize, long byteAlignment)
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.IllegalArgumentException
- if byteSize < 0
, byteAlignment <= 0
, or if byteAlignment
is not a power of 2.static SegmentAllocatorPREVIEW slicingAllocator(MemorySegmentPREVIEW segment)
The returned allocator throws IndexOutOfBoundsException
when a slice of the provided segment with the requested size and alignment cannot be found.
segment
- the segment which the returned allocator should slice from.static SegmentAllocatorPREVIEW prefixAllocator(MemorySegmentPREVIEW segment)
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);
IndexOutOfBoundsException
when a slice of the provided segment with the requested size and alignment cannot be found.segment
- the memory segment to be recycled by the returned allocator.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/SegmentAllocator.html
SegmentAllocator
when preview features are enabled.