Module jdk.incubator.foreign
Package jdk.incubator.foreign

# Interface NativeScope

All Superinterfaces:
  `AutoCloseable`

public interface NativeScope extends AutoCloseable
A native scope is an abstraction which provides shared temporal bounds for one or more allocations, backed by off-heap memory. Native scopes can be either bounded or unbounded, depending on whether the size of the native scope is known statically. If an application knows before-hand how much memory it needs to allocate, then using a bounded native scope will typically provide better performance than independently allocating the memory for each value (e.g. using `MemorySegment.allocateNative(long)`), or using an unbounded native scope. For this reason, using a bounded native scope is recommended in cases where programs might need to emulate native stack allocation.

Allocation scopes are thread-confined (see `ownerThread()`; as such, the resulting `MemorySegment` instances returned by the native scope will be backed by memory segments confined by the same owner thread as the native scope's owner thread.

To allow for more usability, it is possible for a native scope to reclaim ownership of an existing memory segment (see `MemorySegment.handoff(NativeScope)`). This might be useful to allow one or more segments which were independently created to share the same life-cycle as a given native scope - which in turns enables a client to group all memory allocation and usage under a single try-with-resources block.

Unless otherwise specified, passing a `null` argument, or an array argument containing one or more `null` elements to a method in this class causes a `NullPointerException` to be thrown.

API Note:
  In the future, if the Java language permits, `NativeScope` may become a `sealed` interface, which would prohibit subclassing except by explicitly permitted types.

## Method Summary

Modifier and Type
Method
Description
`default MemorySegment`
`allocate​(long bytesSize)`
Allocate a block of memory in this native scope with given size.
`MemorySegment`
`allocate​(long bytesSize, long bytesAlignment)`
Allocate a block of memory in this native scope with given size and alignment constraint.
`default MemorySegment`
`allocate​(MemoryLayout layout)`
Allocate a block of memory in this native scope with given layout.
`default MemorySegment`
`allocate​(ValueLayout layout, byte value)`
Allocate a block of memory in this native scope with given layout and initialize it with given byte value.
`default MemorySegment`
`allocate​(ValueLayout layout, char value)`
Allocate a block of memory in this native scope with given layout and initialize it with given char value.
`default MemorySegment`
`allocate​(ValueLayout layout, double value)`
Allocate a block of memory in this native scope with given layout and initialize it with given double value.
`default MemorySegment`
`allocate​(ValueLayout layout, float value)`
Allocate a block of memory in this native scope with given layout and initialize it with given float value.
`default MemorySegment`
`allocate​(ValueLayout layout, int value)`
Allocate a block of memory in this native scope with given layout and initialize it with given int value.
`default MemorySegment`
`allocate​(ValueLayout layout, long value)`
Allocate a block of memory in this native scope with given layout and initialize it with given long value.
`default MemorySegment`
`allocate​(ValueLayout layout, short value)`
Allocate a block of memory in this native scope with given layout and initialize it with given short value.
`default MemorySegment`
`allocate​(ValueLayout layout, Addressable value)`
Allocate a block of memory in this native scope with given layout and initialize it with given address value (expressed as an `Addressable` instance).
`default MemorySegment`
`allocateArray​(MemoryLayout elementLayout, long count)`
Allocate a block of memory corresponding to an array with given element layout and size.
`default MemorySegment`
`allocateArray​(ValueLayout elementLayout, byte[] array)`
Allocate a block of memory in this native scope with given layout and initialize it with given byte array.
`default MemorySegment`
`allocateArray​(ValueLayout elementLayout, char[] array)`
Allocate a block of memory in this native scope with given layout and initialize it with given char array.
`default MemorySegment`
`allocateArray​(ValueLayout elementLayout, double[] array)`
Allocate a block of memory in this native scope with given layout and initialize it with given double array.
`default MemorySegment`
`allocateArray​(ValueLayout elementLayout, float[] array)`
Allocate a block of memory in this native scope with given layout and initialize it with given float array.
`default MemorySegment`
`allocateArray​(ValueLayout elementLayout, int[] array)`
Allocate a block of memory in this native scope with given layout and initialize it with given int array.
`default MemorySegment`
`allocateArray​(ValueLayout elementLayout, long[] array)`
Allocate a block of memory in this native scope with given layout and initialize it with given long array.
`default MemorySegment`
`allocateArray​(ValueLayout elementLayout, short[] array)`
Allocate a block of memory in this native scope with given layout and initialize it with given short array.
`default MemorySegment`
`allocateArray​(ValueLayout elementLayout, Addressable[] array)`
Allocate a block of memory in this native scope with given layout and initialize it with given address array.
`long`
`allocatedBytes()`
Returns the number of allocated bytes in this native scope.
`static NativeScope`
`boundedScope​(long size)`
Creates a new bounded native scope, backed by off-heap memory.
`OptionalLong`
`byteSize()`
If this native scope is bounded, returns the size, in bytes, of this native scope.
`void`
`close()`
Close this native scope; calling this method will render any segment obtained through this native scope unusable and might release any backing memory resources associated with this native scope.
`Thread`
`ownerThread()`
The thread owning this native scope.
`static NativeScope`
`unboundedScope()`
Creates a new unbounded native scope, backed by off-heap memory.

## Method Details

### byteSize

OptionalLong byteSize()
If this native scope is bounded, returns the size, in bytes, of this native scope.

Returns:
  the size, in bytes, of this native scope (if available).

### ownerThread

Thread ownerThread()
The thread owning this native scope.

Returns:
  the thread owning this native scope.

### allocatedBytes

long allocatedBytes()
Returns the number of allocated bytes in this native scope.

Returns:
  the number of allocated bytes in this native scope.

### allocate

default MemorySegment allocate​(ValueLayout layout, byte value)
Allocate a block of memory in this native scope with given layout and initialize it with given byte value. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

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.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < layout.byteSize()`.
  `IllegalArgumentException` - if `layout.byteSize()` does not conform to the size of a byte value.

### allocate

default MemorySegment allocate​(ValueLayout layout, char value)
Allocate a block of memory in this native scope with given layout and initialize it with given char value. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

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.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < layout.byteSize()`.
  `IllegalArgumentException` - if `layout.byteSize()` does not conform to the size of a char value.

### allocate

default MemorySegment allocate​(ValueLayout layout, short value)
Allocate a block of memory in this native scope with given layout and initialize it with given short value. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

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.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < layout.byteSize()`.
  `IllegalArgumentException` - if `layout.byteSize()` does not conform to the size of a short value.

### allocate

default MemorySegment allocate​(ValueLayout layout, int value)
Allocate a block of memory in this native scope with given layout and initialize it with given int value. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

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.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < layout.byteSize()`.
  `IllegalArgumentException` - if `layout.byteSize()` does not conform to the size of a int value.

### allocate

default MemorySegment allocate​(ValueLayout layout, float value)
Allocate a block of memory in this native scope with given layout and initialize it with given float value. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

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.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < layout.byteSize()`.
  `IllegalArgumentException` - if `layout.byteSize()` does not conform to the size of a float value.

### allocate

default MemorySegment allocate​(ValueLayout layout, long value)
Allocate a block of memory in this native scope with given layout and initialize it with given long value. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

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.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < layout.byteSize()`.
  `IllegalArgumentException` - if `layout.byteSize()` does not conform to the size of a long value.

### allocate

default MemorySegment allocate​(ValueLayout layout, double value)
Allocate a block of memory in this native scope with given layout and initialize it with given double value. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

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.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < layout.byteSize()`.
  `IllegalArgumentException` - if `layout.byteSize()` does not conform to the size of a double value.

### allocate

default MemorySegment allocate​(ValueLayout layout, Addressable value)
Allocate a block of memory in this native scope with given layout and initialize it with given address value (expressed as an `Addressable` instance). The address value might be narrowed according to the platform address size (see `MemoryLayouts.ADDRESS`). The segment returned by this method cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

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.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < layout.byteSize()`.
  `IllegalArgumentException` - if `layout.byteSize() != MemoryLayouts.ADDRESS.byteSize()`.

### allocateArray

default MemorySegment allocateArray​(ValueLayout elementLayout, byte[] array)
Allocate a block of memory in this native scope with given layout and initialize it with given byte array. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

Parameters:
  `elementLayout` - the element layout of the array to be allocated.
  `array` - the array to be copied on the newly allocated memory block.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)`.
  `IllegalArgumentException` - if `elementLayout.byteSize()` does not conform to the size of a byte value.

### allocateArray

default MemorySegment allocateArray​(ValueLayout elementLayout, short[] array)
Allocate a block of memory in this native scope with given layout and initialize it with given short array. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

Parameters:
  `elementLayout` - the element layout of the array to be allocated.
  `array` - the array to be copied on the newly allocated memory block.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)`.
  `IllegalArgumentException` - if `elementLayout.byteSize()` does not conform to the size of a short value.

### allocateArray

default MemorySegment allocateArray​(ValueLayout elementLayout, char[] array)
Allocate a block of memory in this native scope with given layout and initialize it with given char array. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

Parameters:
  `elementLayout` - the element layout of the array to be allocated.
  `array` - the array to be copied on the newly allocated memory block.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)`.
  `IllegalArgumentException` - if `elementLayout.byteSize()` does not conform to the size of a char value.

### allocateArray

default MemorySegment allocateArray​(ValueLayout elementLayout, int[] array)
Allocate a block of memory in this native scope with given layout and initialize it with given int array. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

Parameters:
  `elementLayout` - the element layout of the array to be allocated.
  `array` - the array to be copied on the newly allocated memory block.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)`.
  `IllegalArgumentException` - if `elementLayout.byteSize()` does not conform to the size of a int value.

### allocateArray

default MemorySegment allocateArray​(ValueLayout elementLayout, float[] array)
Allocate a block of memory in this native scope with given layout and initialize it with given float array. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

Parameters:
  `elementLayout` - the element layout of the array to be allocated.
  `array` - the array to be copied on the newly allocated memory block.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)`.
  `IllegalArgumentException` - if `elementLayout.byteSize()` does not conform to the size of a float value.

### allocateArray

default MemorySegment allocateArray​(ValueLayout elementLayout, long[] array)
Allocate a block of memory in this native scope with given layout and initialize it with given long array. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

Parameters:
  `elementLayout` - the element layout of the array to be allocated.
  `array` - the array to be copied on the newly allocated memory block.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)`.
  `IllegalArgumentException` - if `elementLayout.byteSize()` does not conform to the size of a long value.

### allocateArray

default MemorySegment allocateArray​(ValueLayout elementLayout, double[] array)
Allocate a block of memory in this native scope with given layout and initialize it with given double array. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

Parameters:
  `elementLayout` - the element layout of the array to be allocated.
  `array` - the array to be copied on the newly allocated memory block.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)`.
  `IllegalArgumentException` - if `elementLayout.byteSize()` does not conform to the size of a double value.

### allocateArray

default MemorySegment allocateArray​(ValueLayout elementLayout, Addressable[] array)
Allocate a block of memory in this native scope with given layout and initialize it with given address array. The address value of each array element might be narrowed according to the platform address size (see `MemoryLayouts.ADDRESS`). The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

Parameters:
  `elementLayout` - the element layout of the array to be allocated.
  `array` - the array to be copied on the newly allocated memory block.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)`.
  `IllegalArgumentException` - if `layout.byteSize() != MemoryLayouts.ADDRESS.byteSize()`.

### allocate

default MemorySegment allocate​(MemoryLayout layout)
Allocate a block of memory in this native scope with given layout. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints.

Parameters:
  `layout` - the layout of the block of memory to be allocated.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < layout.byteSize()`.

### allocateArray

default MemorySegment allocateArray​(MemoryLayout elementLayout, long count)
Allocate a block of memory corresponding to an array with given element layout and size. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must conform to the layout alignment constraints. This is equivalent to the following code:

        allocate(MemoryLayout.ofSequence(size, elementLayout));

Parameters:
  `elementLayout` - the array element layout.
  `count` - the array element count.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if this is a bounded allocation scope, and `byteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * count)`.

### allocate

default MemorySegment allocate​(long bytesSize)
Allocate a block of memory in this native scope with given size. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must be aligned to `size`.

Parameters:
  `bytesSize` - the size (in bytes) of the block of memory to be allocated.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if `limit() - size() < bytesSize`.

### allocate

MemorySegment allocate​(long bytesSize, long bytesAlignment)
Allocate a block of memory in this native scope with given size and alignment constraint. The segment returned by this method is associated with a segment which cannot be closed. Moreover, the returned segment must be aligned to `alignment`.

Parameters:
  `bytesSize` - the size (in bytes) of the block of memory to be allocated.
  `bytesAlignment` - the alignment (in bytes) of the block of memory to be allocated.
Returns:
  a segment for the newly allocated memory block.
Throws:
  `OutOfMemoryError` - if there is not enough space left in this native scope, that is, if `limit() - size() < bytesSize`.

### close

void close()
Close this native scope; calling this method will render any segment obtained through this native scope unusable and might release any backing memory resources associated with this native scope.

Specified by:
  `close` in interface `AutoCloseable`

### boundedScope

static NativeScope boundedScope​(long size)
Creates a new bounded native scope, backed by off-heap memory.

Parameters:
  `size` - the size of the native scope.
Returns:
  a new bounded native scope, with given size (in bytes).

### unboundedScope

static NativeScope unboundedScope()
Creates a new unbounded native scope, backed by off-heap memory.

Returns:
  a new unbounded native scope.