OpenJDK 27 · java.lang.foreign.SegmentAllocator · APIdia, the JavaDoc alternative

Method Summary

Modifier and Type	Method and Description
public default MemorySegment	Returns: a new memory segment with the given layout allocate(MemoryLayout the layout of the block of memory to be allocated layout) Returns a new memory segment with the given layout.
public default MemorySegment	Returns: a new memory segment with the given `elementLayout` and `count` allocate(MemoryLayout the array element layout elementLayout, long the array element count count) Returns a new memory segment with the given `elementLayout` and `count`.
public default MemorySegment	Returns: a new memory segment with the given `byteSize` allocate(long the size (in bytes) of the block of memory to be allocated byteSize) Returns a new memory segment with the given `byteSize`.
public MemorySegment	Returns: a new memory segment with the given `byteSize` and `byteAlignment` allocate(long the size (in bytes) of the block of memory to be allocated byteSize, long the alignment (in bytes) of the block of memory to be allocated byteAlignment) Returns a new memory segment with the given `byteSize` and `byteAlignment`.
public default MemorySegment	Returns: a new native segment containing the converted C string allocateFrom(String the Java string to be converted into a C string str) Converts a Java string into a null-terminated C string using the UTF-8 charset, storing the result into a memory segment.
public default MemorySegment	Returns: a new native segment containing the converted C string allocateFrom(String the Java string to be converted into a C string str, Charset the charset used to encode the string bytes charset) Converts a Java string into a null-terminated C string using the provided charset, and storing the result into a memory segment.
public default MemorySegment	Returns: a new native segment containing the encoded string allocateFrom(String the Java string to be encoded str, Charset the charset used to encode the string bytes charset, int the starting index of the source string srcIndex, int the number of characters to be copied numChars) Encodes a Java string using the provided charset and stores the resulting byte array into a memory segment.
public default MemorySegment	Returns: a new memory segment initialized with the provided byte value allocateFrom(ValueLayout.OfByte the layout of the block of memory to be allocated layout, byte the value to be set in the newly allocated memory segment value) Returns a new memory segment initialized with the provided byte value.
public default MemorySegment	Returns: a new memory segment initialized with the provided char value allocateFrom(ValueLayout.OfChar the layout of the block of memory to be allocated layout, char the value to be set in the newly allocated memory segment value) Returns a new memory segment initialized with the provided char value.
public default MemorySegment	Returns: a new memory segment initialized with the provided short value allocateFrom(ValueLayout.OfShort the layout of the block of memory to be allocated layout, short the value to be set in the newly allocated memory segment value) Returns a new memory segment initialized with the provided short value.
public default MemorySegment	Returns: a new memory segment initialized with the provided int value allocateFrom(ValueLayout.OfInt the layout of the block of memory to be allocated layout, int the value to be set in the newly allocated memory segment value) Returns a new memory segment initialized with the provided int value.
public default MemorySegment	Returns: a new memory segment initialized with the provided float value allocateFrom(ValueLayout.OfFloat the layout of the block of memory to be allocated layout, float the value to be set in the newly allocated memory segment value) Returns a new memory segment initialized with the provided float value.
public default MemorySegment	Returns: a new memory segment initialized with the provided long value allocateFrom(ValueLayout.OfLong the layout of the block of memory to be allocated layout, long the value to be set in the newly allocated memory segment value) Returns a new memory segment initialized with the provided long value.
public default MemorySegment	Returns: a new memory segment initialized with the provided double value allocateFrom(ValueLayout.OfDouble the layout of the block of memory to be allocated layout, double the value to be set in the newly allocated memory segment value) Returns a new memory segment initialized with the provided double value.
public default MemorySegment	Returns: a new memory segment initialized with the address of the provided memory segment allocateFrom(AddressLayout the layout of the block of memory to be allocated layout, MemorySegment the value to be set in the newly allocated memory segment value) Returns a new memory segment initialized with the address of the provided memory segment.
public default MemorySegment	Returns: a new memory segment initialized with the contents of the provided segment allocateFrom(ValueLayout the element layout of the allocated array elementLayout, MemorySegment the source segment source, ValueLayout the element layout of the source segment sourceElementLayout, long the starting offset, in bytes, of the source segment sourceOffset, long the number of elements in the source segment to be copied elementCount) Returns a new memory segment initialized with the contents of the provided segment.
public default MemorySegment	Returns: a new memory segment initialized with the elements in the provided byte array allocateFrom(ValueLayout.OfByte the element layout of the array to be allocated elementLayout, byte... the byte elements to be copied to the newly allocated memory block elements) Returns a new memory segment initialized with the elements in the provided byte array.
public default MemorySegment	Returns: a new memory segment initialized with the elements in the provided short array allocateFrom(ValueLayout.OfShort the element layout of the array to be allocated elementLayout, short... the short elements to be copied to the newly allocated memory block elements) Returns a new memory segment initialized with the elements in the provided short array.
public default MemorySegment	Returns: a new memory segment initialized with the elements in the provided char array allocateFrom(ValueLayout.OfChar the element layout of the array to be allocated elementLayout, char... the char elements to be copied to the newly allocated memory block elements) Returns a new memory segment initialized with the elements in the provided char array.
public default MemorySegment	Returns: a new memory segment initialized with the elements in the provided int array allocateFrom(ValueLayout.OfInt the element layout of the array to be allocated elementLayout, int... the int elements to be copied to the newly allocated memory block elements) Returns a new memory segment initialized with the elements in the provided int array.
public default MemorySegment	Returns: a new memory segment initialized with the elements in the provided float array allocateFrom(ValueLayout.OfFloat the element layout of the array to be allocated elementLayout, float... the float elements to be copied to the newly allocated memory block elements) Returns a new memory segment initialized with the elements in the provided float array.
public default MemorySegment	Returns: a new memory segment initialized with the elements in the provided long array allocateFrom(ValueLayout.OfLong the element layout of the array to be allocated elementLayout, long... the long elements to be copied to the newly allocated memory block elements) Returns a new memory segment initialized with the elements in the provided long array.
public default MemorySegment	Returns: a new memory segment initialized with the elements in the provided double array allocateFrom(ValueLayout.OfDouble the element layout of the array to be allocated elementLayout, double... the double elements to be copied to the newly allocated memory block elements) Returns a new memory segment initialized with the elements in the provided double array.
private MemorySegment	allocateNoInit(long byteSize)
private MemorySegment	allocateNoInit(MemoryLayout layout)
private MemorySegment	allocateNoInit(MemoryLayout layout, long size)
private static void	assertWritable(MemorySegment segment)
public static SegmentAllocator	Returns: an allocator that recycles an existing segment upon each new allocation request prefixAllocator(MemorySegment the memory segment to be recycled by the returned allocator segment) Returns a segment allocator that responds to allocation requests by recycling a single segment.
public static SegmentAllocator	Returns: a new slicing allocator slicingAllocator(MemorySegment the segment from which the returned allocator should slice from segment) Returns a segment allocator that responds to allocation requests by returning consecutive slices obtained from the provided segment.

Method Detail

allocate back to summary

allocate	back to summary
public default MemorySegment allocate(MemoryLayout layout) Returns a new memory segment with the given layout. Implementation Specification The default implementation for this method calls `this.allocate(layout.byteSize(), layout.byteAlignment())`. Parameters layout:MemoryLayout the layout of the block of memory to be allocated Returns:MemorySegment a new memory segment with the given layout

public default MemorySegment allocate(MemoryLayout layout)

Returns a new memory segment with the given layout.

Implementation Specification

The default implementation for this method calls this.allocate(layout.byteSize(), layout.byteAlignment()).

Parameters

layout:MemoryLayout: the layout of the block of memory to be allocated

Returns:MemorySegment

a new memory segment with the given layout

allocate back to summary

allocate	back to summary
public default MemorySegment allocate(MemoryLayout elementLayout, long count) Returns a new memory segment with the given `elementLayout` and `count`. Implementation Specification The default implementation for this method calls `this.allocate(MemoryLayout.sequenceLayout(count, elementLayout))`. Parameters elementLayout:MemoryLayout the array element layout count:long the array element count Returns:MemorySegment a new memory segment with the given `elementLayout` and `count` Exceptions IllegalArgumentException: if `elementLayout.byteSize() * count` overflows if `count < 0`

public default MemorySegment allocate(MemoryLayout elementLayout, long count)

Returns a new memory segment with the given elementLayout and count.

Implementation Specification

The default implementation for this method calls this.allocate(MemoryLayout.sequenceLayout(count, elementLayout)).

Parameters

elementLayout:MemoryLayout: the array element layout
count:long: the array element count

Returns:MemorySegment

a new memory segment with the given elementLayout and count

Exceptions

IllegalArgumentException:

if elementLayout.byteSize() * count overflows
if count < 0

allocate back to summary

allocate	back to summary
public default MemorySegment allocate(long byteSize) Returns a new memory segment with the given `byteSize`. Implementation Specification The default implementation for this method calls `this.allocate(byteSize, 1)`. Parameters byteSize:long the size (in bytes) of the block of memory to be allocated Returns:MemorySegment a new memory segment with the given `byteSize` Exceptions IllegalArgumentException: if `byteSize < 0`

public default MemorySegment allocate(long byteSize)

Returns a new memory segment with the given byteSize.

Implementation Specification

The default implementation for this method calls this.allocate(byteSize, 1).

Parameters

byteSize:long: the size (in bytes) of the block of memory to be allocated

Returns:MemorySegment

a new memory segment with the given byteSize

Exceptions

IllegalArgumentException:: if byteSize < 0

allocate back to summary

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

public MemorySegment allocate(long byteSize, long byteAlignment)

Returns a new memory segment with the given byteSize and byteAlignment.

Parameters

byteSize:long: the size (in bytes) of the block of memory to be allocated
byteAlignment:long: the alignment (in bytes) of the block of memory to be allocated

Returns:MemorySegment

a new memory segment with the given byteSize and byteAlignment

Exceptions

IllegalArgumentException:: if byteSize < 0, byteAlignment <= 0, or if byteAlignment is not a power of 2

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(String str) Converts a Java string into a null-terminated C string using the UTF-8 charset, storing the result into a memory segment. Calling this method is equivalent to the following code: `allocateFrom(str, StandardCharsets.UTF_8);` allocateFrom(str, StandardCharsets.UTF_8); Parameters str:String the Java string to be converted into a C string Returns:MemorySegment a new native segment containing the converted C string Annotations @ForceInline

public default MemorySegment allocateFrom(String str)

Converts a Java string into a null-terminated C string using the UTF-8 charset, storing the result into a memory segment.

Calling this method is equivalent to the following code:

allocateFrom(str, StandardCharsets.UTF_8);

Parameters

str:String: the Java string to be converted into a C string

Returns:MemorySegment

a new native segment containing the converted C string

Annotations

@ForceInline

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(String str, Charset charset) Converts a Java string into a null-terminated C string using the provided charset, and 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 `java.nio.charset.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#getString(long)`, the string will appear truncated when read again. The string can be read without truncation using `MemorySegment#getString(long, Charset, long)`. Implementation Specification The default implementation for this method copies the contents of the provided Java string into a new memory segment obtained by calling `this.allocate(B + N)`, where: `B` is the size, in bytes, of the string encoded using the provided charset (e.g. `str.getBytes(charset).length`); `N` is the size (in bytes) of the terminator char according to the provided charset. For instance, this is 1 for `StandardCharsets#US_ASCII` and 2 for `StandardCharsets#UTF_16`. Parameters str:String the Java string to be converted into a C string charset:Charset the charset used to encode the string bytes Returns:MemorySegment a new native segment containing the converted C string Annotations @ForceInline Exceptions IllegalArgumentException: if `charset` is not a standard charset

public default MemorySegment allocateFrom(String str, Charset charset)

Converts a Java string into a null-terminated C string using the provided charset, and 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 java.nio.charset.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#getString(long), the string will appear truncated when read again. The string can be read without truncation using MemorySegment#getString(long, Charset, long).

Implementation Specification

The default implementation for this method copies the contents of the provided Java string into a new memory segment obtained by calling this.allocate(B + N), where:

B is the size, in bytes, of the string encoded using the provided charset (e.g. str.getBytes(charset).length);
N is the size (in bytes) of the terminator char according to the provided charset. For instance, this is 1 for StandardCharsets#US_ASCII and 2 for StandardCharsets#UTF_16.

Parameters

str:String: the Java string to be converted into a C string
charset:Charset: the charset used to encode the string bytes

Returns:MemorySegment

a new native segment containing the converted C string

Annotations

@ForceInline

Exceptions

IllegalArgumentException:: if charset is not a standard charset

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(String str, Charset charset, int srcIndex, int numChars) Encodes a Java string using the provided charset and stores the resulting byte array into a memory segment. This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement byte array. The `java.nio.charset.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#getString(long)`, the string will appear truncated when read again. The string can be read without truncation using `MemorySegment#getString(long, Charset, long)`. Implementation Specification The default implementation for this method copies the contents of the provided Java string into a new memory segment obtained by calling `this.allocate(B)`, where `B` is the size, in bytes, of the string encoded using the provided charset (e.g. `str.getBytes(charset).length`); Parameters str:String the Java string to be encoded charset:Charset the charset used to encode the string bytes srcIndex:int the starting index of the source string numChars:int the number of characters to be copied Returns:MemorySegment a new native segment containing the encoded string Annotations @ForceInline Exceptions IndexOutOfBoundsException: if either `srcIndex` or `numChars` are `< 0` if `srcIndex > str.length() - numChars` Since 27

public default MemorySegment allocateFrom(String str, Charset charset, int srcIndex, int numChars)

Encodes a Java string using the provided charset and stores the resulting byte array into a memory segment.

Implementation Specification

The default implementation for this method copies the contents of the provided Java string into a new memory segment obtained by calling this.allocate(B), where B is the size, in bytes, of the string encoded using the provided charset (e.g. str.getBytes(charset).length);

Parameters

str:String: the Java string to be encoded
charset:Charset: the charset used to encode the string bytes
srcIndex:int: the starting index of the source string
numChars:int: the number of characters to be copied

Returns:MemorySegment

a new native segment containing the encoded string

Annotations

@ForceInline

Exceptions

IndexOutOfBoundsException:

if either srcIndex or numChars are < 0
if srcIndex > str.length() - numChars

Since

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfByte layout, byte value) Returns a new memory segment initialized with the provided byte value. The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout. Implementation Specification The default implementation is equivalent to: `MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg;` MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg; Parameters layout:ValueLayout.OfByte the layout of the block of memory to be allocated value:byte the value to be set in the newly allocated memory segment Returns:MemorySegment a new memory segment initialized with the provided byte value

public default MemorySegment allocateFrom(ValueLayout.OfByte layout, byte value)

Returns a new memory segment initialized with the provided byte value.

The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout.

Implementation Specification

The default implementation is equivalent to:

MemorySegment seg = allocate(Objects.requireNonNull(layout));
seg.set(layout, 0, value);
return seg;

Parameters

layout:ValueLayout.OfByte: the layout of the block of memory to be allocated
value:byte: the value to be set in the newly allocated memory segment

Returns:MemorySegment

a new memory segment initialized with the provided byte value

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfChar layout, char value) Returns a new memory segment initialized with the provided char value. The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout. Implementation Specification The default implementation is equivalent to: `MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg;` MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg; Parameters layout:ValueLayout.OfChar the layout of the block of memory to be allocated value:char the value to be set in the newly allocated memory segment Returns:MemorySegment a new memory segment initialized with the provided char value

public default MemorySegment allocateFrom(ValueLayout.OfChar layout, char value)

Returns a new memory segment initialized with the provided char value.

The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout.

Implementation Specification

The default implementation is equivalent to:

MemorySegment seg = allocate(Objects.requireNonNull(layout));
seg.set(layout, 0, value);
return seg;

Parameters

layout:ValueLayout.OfChar: the layout of the block of memory to be allocated
value:char: the value to be set in the newly allocated memory segment

Returns:MemorySegment

a new memory segment initialized with the provided char value

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfShort layout, short value) Returns a new memory segment initialized with the provided short value. The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout. Implementation Specification The default implementation is equivalent to: `MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg;` MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg; Parameters layout:ValueLayout.OfShort the layout of the block of memory to be allocated value:short the value to be set in the newly allocated memory segment Returns:MemorySegment a new memory segment initialized with the provided short value

public default MemorySegment allocateFrom(ValueLayout.OfShort layout, short value)

Returns a new memory segment initialized with the provided short value.

The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout.

Implementation Specification

The default implementation is equivalent to:

MemorySegment seg = allocate(Objects.requireNonNull(layout));
seg.set(layout, 0, value);
return seg;

Parameters

layout:ValueLayout.OfShort: the layout of the block of memory to be allocated
value:short: the value to be set in the newly allocated memory segment

Returns:MemorySegment

a new memory segment initialized with the provided short value

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfInt layout, int value) Returns a new memory segment initialized with the provided int value. The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout. Implementation Specification The default implementation is equivalent to: `MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg;` MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg; Parameters layout:ValueLayout.OfInt the layout of the block of memory to be allocated value:int the value to be set in the newly allocated memory segment Returns:MemorySegment a new memory segment initialized with the provided int value

public default MemorySegment allocateFrom(ValueLayout.OfInt layout, int value)

Returns a new memory segment initialized with the provided int value.

The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout.

Implementation Specification

The default implementation is equivalent to:

MemorySegment seg = allocate(Objects.requireNonNull(layout));
seg.set(layout, 0, value);
return seg;

Parameters

layout:ValueLayout.OfInt: the layout of the block of memory to be allocated
value:int: the value to be set in the newly allocated memory segment

Returns:MemorySegment

a new memory segment initialized with the provided int value

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfFloat layout, float value) Returns a new memory segment initialized with the provided float value. The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout. Implementation Specification The default implementation is equivalent to: `MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg;` MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg; Parameters layout:ValueLayout.OfFloat the layout of the block of memory to be allocated value:float the value to be set in the newly allocated memory segment Returns:MemorySegment a new memory segment initialized with the provided float value

public default MemorySegment allocateFrom(ValueLayout.OfFloat layout, float value)

Returns a new memory segment initialized with the provided float value.

The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout.

Implementation Specification

The default implementation is equivalent to:

MemorySegment seg = allocate(Objects.requireNonNull(layout));
seg.set(layout, 0, value);
return seg;

Parameters

layout:ValueLayout.OfFloat: the layout of the block of memory to be allocated
value:float: the value to be set in the newly allocated memory segment

Returns:MemorySegment

a new memory segment initialized with the provided float value

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfLong layout, long value) Returns a new memory segment initialized with the provided long value. The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout. Implementation Specification The default implementation is equivalent to: `MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg;` MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg; Parameters layout:ValueLayout.OfLong the layout of the block of memory to be allocated value:long the value to be set in the newly allocated memory segment Returns:MemorySegment a new memory segment initialized with the provided long value

public default MemorySegment allocateFrom(ValueLayout.OfLong layout, long value)

Returns a new memory segment initialized with the provided long value.

The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout.

Implementation Specification

The default implementation is equivalent to:

MemorySegment seg = allocate(Objects.requireNonNull(layout));
seg.set(layout, 0, value);
return seg;

Parameters

layout:ValueLayout.OfLong: the layout of the block of memory to be allocated
value:long: the value to be set in the newly allocated memory segment

Returns:MemorySegment

a new memory segment initialized with the provided long value

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfDouble layout, double value) Returns a new memory segment initialized with the provided double value. The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout. Implementation Specification The default implementation is equivalent to: `MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg;` MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg; Parameters layout:ValueLayout.OfDouble the layout of the block of memory to be allocated value:double the value to be set in the newly allocated memory segment Returns:MemorySegment a new memory segment initialized with the provided double value

public default MemorySegment allocateFrom(ValueLayout.OfDouble layout, double value)

Returns a new memory segment initialized with the provided double value.

The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout.

Implementation Specification

The default implementation is equivalent to:

MemorySegment seg = allocate(Objects.requireNonNull(layout));
seg.set(layout, 0, value);
return seg;

Parameters

layout:ValueLayout.OfDouble: the layout of the block of memory to be allocated
value:double: the value to be set in the newly allocated memory segment

Returns:MemorySegment

a new memory segment initialized with the provided double value

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(AddressLayout layout, MemorySegment value) Returns a new memory segment initialized with the address of the provided memory segment. The address value might be narrowed according to the platform address size (see `ValueLayout#ADDRESS`). The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout. Implementation Specification The default implementation is equivalent to: `Objects.requireNonNull(value); MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg;` Objects.requireNonNull(value); MemorySegment seg = allocate(Objects.requireNonNull(layout)); seg.set(layout, 0, value); return seg; Parameters layout:AddressLayout the layout of the block of memory to be allocated value:MemorySegment the value to be set in the newly allocated memory segment Returns:MemorySegment a new memory segment initialized with the address of the provided memory segment Exceptions IllegalArgumentException: if `value` is not a native segment

public default MemorySegment allocateFrom(AddressLayout layout, MemorySegment value)

Returns a new memory segment initialized with the address of the provided memory segment.

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

The size of the allocated memory segment is the size of the given layout. The given value is written into the segment according to the byte order and alignment constraint of the given layout.

Implementation Specification

The default implementation is equivalent to:

Objects.requireNonNull(value);
MemorySegment seg = allocate(Objects.requireNonNull(layout));
seg.set(layout, 0, value);
return seg;

Parameters

layout:AddressLayout: the layout of the block of memory to be allocated
value:MemorySegment: the value to be set in the newly allocated memory segment

Returns:MemorySegment

a new memory segment initialized with the address of the provided memory segment

Exceptions

IllegalArgumentException:: if value is not a native segment

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout elementLayout, MemorySegment source, ValueLayout sourceElementLayout, long sourceOffset, long elementCount) Returns a new memory segment initialized with the contents of the provided segment. The size of the allocated memory segment is the `elementLayout.byteSize() * elementCount`. The contents of the source segment is copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout. Implementation Specification The default implementation for this method is equivalent to the following code: `MemorySegment dest = this.allocate(elementLayout, elementCount); MemorySegment.copy(source, sourceElementLayout, sourceOffset, dest, elementLayout, 0, elementCount); return dest;` MemorySegment dest = this.allocate(elementLayout, elementCount); MemorySegment.copy(source, sourceElementLayout, sourceOffset, dest, elementLayout, 0, elementCount); return dest; Parameters elementLayout:ValueLayout the element layout of the allocated array source:MemorySegment the source segment sourceElementLayout:ValueLayout the element layout of the source segment sourceOffset:long the starting offset, in bytes, of the source segment elementCount:long the number of elements in the source segment to be copied Returns:MemorySegment a new memory segment initialized with the contents of the provided segment Annotations @ForceInline Exceptions IllegalArgumentException: if `elementLayout.byteSize() != sourceElementLayout.byteSize()` if the source segment/offset are incompatible with the alignment constraint in the source element layout if `elementLayout.byteAlignment() > elementLayout.byteSize()` if `sourceElementLayout.byteAlignment() > sourceElementLayout.byteSize()` if `elementCount * sourceElementLayout.byteSize()` overflows if `elementCount < 0` IllegalStateException: if the scope associated with `source` is not alive WrongThreadException: if this method is called from a thread `T`, such that `source.isAccessibleBy(T) == false` IndexOutOfBoundsException: if `sourceOffset > source.byteSize() - (elementCount * sourceElementLayout.byteSize())` if `sourceOffset < 0`

public default MemorySegment allocateFrom(ValueLayout elementLayout, MemorySegment source, ValueLayout sourceElementLayout, long sourceOffset, long elementCount)

Returns a new memory segment initialized with the contents of the provided segment.

The size of the allocated memory segment is the elementLayout.byteSize() * elementCount. The contents of the source segment is copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout.

Implementation Specification

The default implementation for this method is equivalent to the following code:

MemorySegment dest = this.allocate(elementLayout, elementCount);
MemorySegment.copy(source, sourceElementLayout, sourceOffset, dest, elementLayout, 0, elementCount);
return dest;

Parameters

elementLayout:ValueLayout: the element layout of the allocated array
source:MemorySegment: the source segment
sourceElementLayout:ValueLayout: the element layout of the source segment
sourceOffset:long: the starting offset, in bytes, of the source segment
elementCount:long: the number of elements in the source segment to be copied

Returns:MemorySegment

a new memory segment initialized with the contents of the provided segment

Annotations

@ForceInline

Exceptions

IllegalArgumentException:

if elementLayout.byteSize() != sourceElementLayout.byteSize()
if the source segment/offset are incompatible with the alignment constraint in the source element layout
if elementLayout.byteAlignment() > elementLayout.byteSize()
if sourceElementLayout.byteAlignment() > sourceElementLayout.byteSize()
if elementCount * sourceElementLayout.byteSize() overflows
if elementCount < 0

IllegalStateException:

if the scope associated with source is not alive

WrongThreadException:

if this method is called from a thread T, such that source.isAccessibleBy(T) == false

IndexOutOfBoundsException:

if sourceOffset > source.byteSize() - (elementCount * sourceElementLayout.byteSize())
if sourceOffset < 0

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfByte elementLayout, byte... elements) Returns a new memory segment initialized with the elements in the provided byte array. The size of the allocated memory segment is `elementLayout.byteSize() * elements.length`. The contents of the source array is copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout. Implementation Specification The default implementation for this method is equivalent to the following code: `this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_BYTE, 0, array.length)` this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_BYTE, 0, array.length) Parameters elementLayout:ValueLayout.OfByte the element layout of the array to be allocated elements:byte[] the byte elements to be copied to the newly allocated memory block Returns:MemorySegment a new memory segment initialized with the elements in the provided byte array Annotations @ForceInline Exceptions IllegalArgumentException: if `elementLayout.byteAlignment() > elementLayout.byteSize()`

public default MemorySegment allocateFrom(ValueLayout.OfByte elementLayout, byte... elements)

Returns a new memory segment initialized with the elements in the provided byte array.

The size of the allocated memory segment is elementLayout.byteSize() * elements.length. The contents of the source array is copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout.

Implementation Specification

The default implementation for this method is equivalent to the following code:

this.allocateFrom(layout, MemorySegment.ofArray(array),
                  ValueLayout.JAVA_BYTE, 0, array.length)

Parameters

elementLayout:ValueLayout.OfByte: the element layout of the array to be allocated
elements:byte[]: the byte elements to be copied to the newly allocated memory block

Returns:MemorySegment

a new memory segment initialized with the elements in the provided byte array

Annotations

@ForceInline

Exceptions

IllegalArgumentException:: if elementLayout.byteAlignment() > elementLayout.byteSize()

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfShort elementLayout, short... elements) Returns a new memory segment initialized with the elements in the provided short array. The size of the allocated memory segment is `elementLayout.byteSize() * elements.length`. The contents of the source array are copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout. Implementation Specification The default implementation for this method is equivalent to the following code: `this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_SHORT, 0, array.length)` this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_SHORT, 0, array.length) Parameters elementLayout:ValueLayout.OfShort the element layout of the array to be allocated elements:short[] the short elements to be copied to the newly allocated memory block Returns:MemorySegment a new memory segment initialized with the elements in the provided short array Annotations @ForceInline Exceptions IllegalArgumentException: if `elementLayout.byteAlignment() > elementLayout.byteSize()`

public default MemorySegment allocateFrom(ValueLayout.OfShort elementLayout, short... elements)

Returns a new memory segment initialized with the elements in the provided short array.

The size of the allocated memory segment is elementLayout.byteSize() * elements.length. The contents of the source array are copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout.

Implementation Specification

The default implementation for this method is equivalent to the following code:

this.allocateFrom(layout, MemorySegment.ofArray(array),
                  ValueLayout.JAVA_SHORT, 0, array.length)

Parameters

elementLayout:ValueLayout.OfShort: the element layout of the array to be allocated
elements:short[]: the short elements to be copied to the newly allocated memory block

Returns:MemorySegment

a new memory segment initialized with the elements in the provided short array

Annotations

@ForceInline

Exceptions

IllegalArgumentException:: if elementLayout.byteAlignment() > elementLayout.byteSize()

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfChar elementLayout, char... elements) Returns a new memory segment initialized with the elements in the provided char array. The size of the allocated memory segment is `elementLayout.byteSize() * elements.length`. The contents of the source array is copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout. Implementation Specification The default implementation for this method is equivalent to the following code: `this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_CHAR, 0, array.length)` this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_CHAR, 0, array.length) Parameters elementLayout:ValueLayout.OfChar the element layout of the array to be allocated elements:char[] the char elements to be copied to the newly allocated memory block Returns:MemorySegment a new memory segment initialized with the elements in the provided char array Annotations @ForceInline Exceptions IllegalArgumentException: if `elementLayout.byteAlignment() > elementLayout.byteSize()`

public default MemorySegment allocateFrom(ValueLayout.OfChar elementLayout, char... elements)

Returns a new memory segment initialized with the elements in the provided char array.

Implementation Specification

The default implementation for this method is equivalent to the following code:

this.allocateFrom(layout, MemorySegment.ofArray(array),
                  ValueLayout.JAVA_CHAR, 0, array.length)

Parameters

elementLayout:ValueLayout.OfChar: the element layout of the array to be allocated
elements:char[]: the char elements to be copied to the newly allocated memory block

Returns:MemorySegment

a new memory segment initialized with the elements in the provided char array

Annotations

@ForceInline

Exceptions

IllegalArgumentException:: if elementLayout.byteAlignment() > elementLayout.byteSize()

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfInt elementLayout, int... elements) Returns a new memory segment initialized with the elements in the provided int array. The size of the allocated memory segment is `elementLayout.byteSize() * elements.length`. The contents of the source array is copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout. Implementation Specification The default implementation for this method is equivalent to the following code: `this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_INT, 0, array.length)` this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_INT, 0, array.length) Parameters elementLayout:ValueLayout.OfInt the element layout of the array to be allocated elements:int[] the int elements to be copied to the newly allocated memory block Returns:MemorySegment a new memory segment initialized with the elements in the provided int array Annotations @ForceInline Exceptions IllegalArgumentException: if `elementLayout.byteAlignment() > elementLayout.byteSize()`

public default MemorySegment allocateFrom(ValueLayout.OfInt elementLayout, int... elements)

Returns a new memory segment initialized with the elements in the provided int array.

Implementation Specification

The default implementation for this method is equivalent to the following code:

this.allocateFrom(layout, MemorySegment.ofArray(array),
                  ValueLayout.JAVA_INT, 0, array.length)

Parameters

elementLayout:ValueLayout.OfInt: the element layout of the array to be allocated
elements:int[]: the int elements to be copied to the newly allocated memory block

Returns:MemorySegment

a new memory segment initialized with the elements in the provided int array

Annotations

@ForceInline

Exceptions

IllegalArgumentException:: if elementLayout.byteAlignment() > elementLayout.byteSize()

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfFloat elementLayout, float... elements) Returns a new memory segment initialized with the elements in the provided float array. The size of the allocated memory segment is `elementLayout.byteSize() * elements.length`. The contents of the source array is copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout. Implementation Specification The default implementation for this method is equivalent to the following code: `this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_FLOAT, 0, array.length)` this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_FLOAT, 0, array.length) Parameters elementLayout:ValueLayout.OfFloat the element layout of the array to be allocated elements:float[] the float elements to be copied to the newly allocated memory block Returns:MemorySegment a new memory segment initialized with the elements in the provided float array Annotations @ForceInline Exceptions IllegalArgumentException: if `elementLayout.byteAlignment() > elementLayout.byteSize()`

public default MemorySegment allocateFrom(ValueLayout.OfFloat elementLayout, float... elements)

Returns a new memory segment initialized with the elements in the provided float array.

Implementation Specification

The default implementation for this method is equivalent to the following code:

this.allocateFrom(layout, MemorySegment.ofArray(array),
                  ValueLayout.JAVA_FLOAT, 0, array.length)

Parameters

elementLayout:ValueLayout.OfFloat: the element layout of the array to be allocated
elements:float[]: the float elements to be copied to the newly allocated memory block

Returns:MemorySegment

a new memory segment initialized with the elements in the provided float array

Annotations

@ForceInline

Exceptions

IllegalArgumentException:: if elementLayout.byteAlignment() > elementLayout.byteSize()

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfLong elementLayout, long... elements) Returns a new memory segment initialized with the elements in the provided long array. The size of the allocated memory segment is `elementLayout.byteSize() * elements.length`. The contents of the source array is copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout. Implementation Specification The default implementation for this method is equivalent to the following code: `this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_LONG, 0, array.length)` this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_LONG, 0, array.length) Parameters elementLayout:ValueLayout.OfLong the element layout of the array to be allocated elements:long[] the long elements to be copied to the newly allocated memory block Returns:MemorySegment a new memory segment initialized with the elements in the provided long array Annotations @ForceInline Exceptions IllegalArgumentException: if `elementLayout.byteAlignment() > elementLayout.byteSize()`

public default MemorySegment allocateFrom(ValueLayout.OfLong elementLayout, long... elements)

Returns a new memory segment initialized with the elements in the provided long array.

Implementation Specification

The default implementation for this method is equivalent to the following code:

this.allocateFrom(layout, MemorySegment.ofArray(array),
                  ValueLayout.JAVA_LONG, 0, array.length)

Parameters

elementLayout:ValueLayout.OfLong: the element layout of the array to be allocated
elements:long[]: the long elements to be copied to the newly allocated memory block

Returns:MemorySegment

a new memory segment initialized with the elements in the provided long array

Annotations

@ForceInline

Exceptions

IllegalArgumentException:: if elementLayout.byteAlignment() > elementLayout.byteSize()

allocateFrom back to summary

allocateFrom	back to summary
public default MemorySegment allocateFrom(ValueLayout.OfDouble elementLayout, double... elements) Returns a new memory segment initialized with the elements in the provided double array. The size of the allocated memory segment is `elementLayout.byteSize() * elements.length`. The contents of the source array is copied into the result segment element by element, according to the byte order and alignment constraint of the given element layout. Implementation Specification The default implementation for this method is equivalent to the following code: `this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_DOUBLE, 0, array.length)` this.allocateFrom(layout, MemorySegment.ofArray(array), ValueLayout.JAVA_DOUBLE, 0, array.length) Parameters elementLayout:ValueLayout.OfDouble the element layout of the array to be allocated elements:double[] the double elements to be copied to the newly allocated memory block Returns:MemorySegment a new memory segment initialized with the elements in the provided double array Annotations @ForceInline Exceptions IllegalArgumentException: if `elementLayout.byteAlignment() > elementLayout.byteSize()`

public default MemorySegment allocateFrom(ValueLayout.OfDouble elementLayout, double... elements)

Returns a new memory segment initialized with the elements in the provided double array.

Implementation Specification

The default implementation for this method is equivalent to the following code:

this.allocateFrom(layout, MemorySegment.ofArray(array),
                  ValueLayout.JAVA_DOUBLE, 0, array.length)

Parameters

elementLayout:ValueLayout.OfDouble: the element layout of the array to be allocated
elements:double[]: the double elements to be copied to the newly allocated memory block

Returns:MemorySegment

a new memory segment initialized with the elements in the provided double array

Annotations

@ForceInline

Exceptions

IllegalArgumentException:: if elementLayout.byteAlignment() > elementLayout.byteSize()

allocateNoInit	back to summary
private MemorySegment allocateNoInit(long byteSize) Annotations @ForceInline

allocateNoInit	back to summary
private MemorySegment allocateNoInit(MemoryLayout layout) Annotations @ForceInline

allocateNoInit	back to summary
private MemorySegment allocateNoInit(MemoryLayout layout, long size) Annotations @ForceInline

assertWritable	back to summary
private static void assertWritable(MemorySegment segment)

prefixAllocator back to summary

prefixAllocator	back to summary
public static SegmentAllocator prefixAllocator(MemorySegment segment) Returns a segment allocator that 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);` 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:MemorySegment the memory segment to be recycled by the returned allocator Returns:SegmentAllocator an allocator that recycles an existing segment upon each new allocation request Exceptions IllegalArgumentException: if the `segment` is read-only

public static SegmentAllocator prefixAllocator(MemorySegment segment)

Returns a segment allocator that 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:MemorySegment: the memory segment to be recycled by the returned allocator

Returns:SegmentAllocator

an allocator that recycles an existing segment upon each new allocation request

Exceptions

IllegalArgumentException:: if the segment is read-only

slicingAllocator back to summary

slicingAllocator	back to summary
public static SegmentAllocator slicingAllocator(MemorySegment segment) Returns a segment allocator that 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:MemorySegment the segment from which the returned allocator should slice from Returns:SegmentAllocator a new slicing allocator Exceptions IllegalArgumentException: if the `segment` is read-only

public static SegmentAllocator slicingAllocator(MemorySegment segment)

Returns a segment allocator that 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:MemorySegment: the segment from which the returned allocator should slice from

Returns:SegmentAllocator

a new slicing allocator

Exceptions

IllegalArgumentException:: if the segment is read-only

public Interface SegmentAllocator

Method Summary

Method Detail