- Functional Interface:
- This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
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.
- 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.
-
Method Summary
Modifier and TypeMethodDescriptiondefault MemorySegmentPREVIEW
allocate
(long byteSize) Allocates a memory segment with the given size.allocate
(long byteSize, long byteAlignment) Allocates a memory segment with the given size and alignment constraint.default MemorySegmentPREVIEW
allocate
(AddressLayoutPREVIEW layout, MemorySegmentPREVIEW value) Allocates a memory segment with the given layout and initializes it with the given address value.default MemorySegmentPREVIEW
allocate
(MemoryLayoutPREVIEW layout) Allocates a memory segment with the given layout.default MemorySegmentPREVIEW
allocate
(ValueLayout.OfBytePREVIEW layout, byte value) Allocates a memory segment with the given layout and initializes it with the given byte value.default MemorySegmentPREVIEW
allocate
(ValueLayout.OfCharPREVIEW layout, char value) Allocates a memory segment with the given layout and initializes it with the given char value.default MemorySegmentPREVIEW
allocate
(ValueLayout.OfDoublePREVIEW layout, double value) Allocates a memory segment with the given layout and initializes it with the given double value.default MemorySegmentPREVIEW
allocate
(ValueLayout.OfFloatPREVIEW layout, float value) Allocates a memory segment with the given layout and initializes it with the given float value.default MemorySegmentPREVIEW
allocate
(ValueLayout.OfIntPREVIEW layout, int value) Allocates a memory segment with the given layout and initializes it with the given int value.default MemorySegmentPREVIEW
allocate
(ValueLayout.OfLongPREVIEW layout, long value) Allocates a memory segment with the given layout and initializes it with the given long value.default MemorySegmentPREVIEW
allocate
(ValueLayout.OfShortPREVIEW layout, short value) Allocates a memory segment with the given layout and initializes it with the given short value.default MemorySegmentPREVIEW
allocateArray
(MemoryLayoutPREVIEW elementLayout, long count) Allocates a memory segment with the given element layout and size.default MemorySegmentPREVIEW
allocateArray
(ValueLayout.OfBytePREVIEW elementLayout, byte... elements) Allocates a memory segment with the given layout and initializes it with the given byte elements.default MemorySegmentPREVIEW
allocateArray
(ValueLayout.OfCharPREVIEW elementLayout, char... elements) Allocates a memory segment with the given layout and initializes it with the given char elements.default MemorySegmentPREVIEW
allocateArray
(ValueLayout.OfDoublePREVIEW elementLayout, double... elements) Allocates a memory segment with the given layout and initializes it with the given double elements.default MemorySegmentPREVIEW
allocateArray
(ValueLayout.OfFloatPREVIEW elementLayout, float... elements) Allocates a memory segment with the given layout and initializes it with the given float elements.default MemorySegmentPREVIEW
allocateArray
(ValueLayout.OfIntPREVIEW elementLayout, int... elements) Allocates a memory segment with the given layout and initializes it with the given int elements.default MemorySegmentPREVIEW
allocateArray
(ValueLayout.OfLongPREVIEW elementLayout, long... elements) Allocates a memory segment with the given layout and initializes it with the given long elements.default MemorySegmentPREVIEW
allocateArray
(ValueLayout.OfShortPREVIEW elementLayout, short... elements) Allocates a memory segment with the given layout and initializes it with the given short elements.default MemorySegmentPREVIEW
allocateUtf8String
(String str) Converts a Java string into a UTF-8 encoded, null-terminated C string, storing the result into a memory segment.static SegmentAllocatorPREVIEW
prefixAllocator
(MemorySegmentPREVIEW segment) Returns a segment allocator which responds to allocation requests by recycling a single segment.static SegmentAllocatorPREVIEW
slicingAllocator
(MemorySegmentPREVIEW segment) Returns a segment allocator which responds to allocation requests by returning consecutive slices obtained from the provided segment.
-
Method Details
-
allocateUtf8String
Converts a Java string into a UTF-8 encoded, null-terminated C string, storing the result into a memory segment.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 asMemorySegment.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 native segment containing the converted C string.
-
allocate
Allocates a memory segment with the given layout and initializes it with the given byte value.- Implementation Requirements:
- the default implementation for this method calls
this.allocate(layout)
. - Parameters:
layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocate
Allocates a memory segment with the given layout and initializes it with the given char value.- Implementation Requirements:
- the default implementation for this method calls
this.allocate(layout)
. - Parameters:
layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocate
Allocates a memory segment with the given layout and initializes it with the given short value.- Implementation Requirements:
- the default implementation for this method calls
this.allocate(layout)
. - Parameters:
layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocate
Allocates a memory segment with the given layout and initializes it with the given int value.- Implementation Requirements:
- the default implementation for this method calls
this.allocate(layout)
. - Parameters:
layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocate
Allocates a memory segment with the given layout and initializes it with the given float value.- Implementation Requirements:
- the default implementation for this method calls
this.allocate(layout)
. - Parameters:
layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocate
Allocates a memory segment with the given layout and initializes it with the given long value.- Implementation Requirements:
- the default implementation for this method calls
this.allocate(layout)
. - Parameters:
layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocate
Allocates a memory segment with the given layout and initializes it with the given double value.- Implementation Requirements:
- the default implementation for this method calls
this.allocate(layout)
. - Parameters:
layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocate
Allocates a memory segment with the given layout and initializes it with the given address value. The address value might be narrowed according to the platform address size (seeValueLayout.ADDRESS
PREVIEW).- Implementation Requirements:
- the default implementation for this method calls
this.allocate(layout)
. - Parameters:
layout
- the layout of the block of memory to be allocated.value
- the value to be set on the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocateArray
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfBytePREVIEW elementLayout, byte... elements) Allocates a memory segment with the given layout and initializes it with the given byte elements.- Implementation Requirements:
- the default implementation for this method calls
this.allocateArray(layout, array.length)
. - Parameters:
elementLayout
- the element layout of the array to be allocated.elements
- the byte elements to be copied to the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocateArray
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfShortPREVIEW elementLayout, short... elements) Allocates a memory segment with the given layout and initializes it with the given short elements.- Implementation Requirements:
- the default implementation for this method calls
this.allocateArray(layout, array.length)
. - 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 segment for the newly allocated memory block.
-
allocateArray
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfCharPREVIEW elementLayout, char... elements) Allocates a memory segment with the given layout and initializes it with the given char elements.- Implementation Requirements:
- the default implementation for this method calls
this.allocateArray(layout, array.length)
. - Parameters:
elementLayout
- the element layout of the array to be allocated.elements
- the char elements to be copied to the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocateArray
Allocates a memory segment with the given layout and initializes it with the given int elements.- Implementation Requirements:
- the default implementation for this method calls
this.allocateArray(layout, array.length)
. - Parameters:
elementLayout
- the element layout of the array to be allocated.elements
- the int elements to be copied to the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocateArray
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfFloatPREVIEW elementLayout, float... elements) Allocates a memory segment with the given layout and initializes it with the given float elements.- Implementation Requirements:
- the default implementation for this method calls
this.allocateArray(layout, array.length)
. - Parameters:
elementLayout
- the element layout of the array to be allocated.elements
- the float elements to be copied to the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocateArray
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfLongPREVIEW elementLayout, long... elements) Allocates a memory segment with the given layout and initializes it with the given long elements.- Implementation Requirements:
- the default implementation for this method calls
this.allocateArray(layout, array.length)
. - Parameters:
elementLayout
- the element layout of the array to be allocated.elements
- the long elements to be copied to the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocateArray
default MemorySegmentPREVIEW allocateArray(ValueLayout.OfDoublePREVIEW elementLayout, double... elements) Allocates a memory segment with the given layout and initializes it with the given double elements.- Implementation Requirements:
- the default implementation for this method calls
this.allocateArray(layout, array.length)
. - Parameters:
elementLayout
- the element layout of the array to be allocated.elements
- the double elements to be copied to the newly allocated memory block.- Returns:
- a segment for the newly allocated memory block.
-
allocate
Allocates a 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 segment for the newly allocated memory block.
-
allocateArray
Allocates a memory segment with the given element layout and size.- 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 segment for the newly allocated memory block.
- Throws:
IllegalArgumentException
- ifelementLayout.byteSize() * count
overflows.IllegalArgumentException
- ifcount < 0
.
-
allocate
Allocates a memory segment with the given size.- 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 segment for the newly allocated memory block.
- Throws:
IllegalArgumentException
- ifbyteSize < 0
-
allocate
Allocates a memory segment with the given size and alignment constraint.- 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 segment for the newly allocated memory block.
- Throws:
IllegalArgumentException
- ifbyteSize < 0
,byteAlignment <= 0
, or ifbyteAlignment
is not a power of 2.
-
slicingAllocator
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
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 offset0
, 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.- 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.
-
SegmentAllocator
when preview features are enabled.