- All Superinterfaces:
AutoCloseable
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 asealed
interface, which would prohibit subclassing except by explicitly permitted types.
-
Method Summary
Modifier and TypeMethodDescriptiondefault MemorySegment
allocate(long bytesSize)
Allocate a block of memory in this native scope with given size.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 anAddressable
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
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.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.The thread owning this native scope.static NativeScope
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
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, andbyteSize().getAsLong() - allocatedBytes() < layout.byteSize()
.IllegalArgumentException
- iflayout.byteSize()
does not conform to the size of a byte value.
-
allocate
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, andbyteSize().getAsLong() - allocatedBytes() < layout.byteSize()
.IllegalArgumentException
- iflayout.byteSize()
does not conform to the size of a char value.
-
allocate
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, andbyteSize().getAsLong() - allocatedBytes() < layout.byteSize()
.IllegalArgumentException
- iflayout.byteSize()
does not conform to the size of a short value.
-
allocate
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, andbyteSize().getAsLong() - allocatedBytes() < layout.byteSize()
.IllegalArgumentException
- iflayout.byteSize()
does not conform to the size of a int value.
-
allocate
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, andbyteSize().getAsLong() - allocatedBytes() < layout.byteSize()
.IllegalArgumentException
- iflayout.byteSize()
does not conform to the size of a float value.
-
allocate
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, andbyteSize().getAsLong() - allocatedBytes() < layout.byteSize()
.IllegalArgumentException
- iflayout.byteSize()
does not conform to the size of a long value.
-
allocate
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, andbyteSize().getAsLong() - allocatedBytes() < layout.byteSize()
.IllegalArgumentException
- iflayout.byteSize()
does not conform to the size of a double value.
-
allocate
Allocate a block of memory in this native scope with given layout and initialize it with given address value (expressed as anAddressable
instance). The address value might be narrowed according to the platform address size (seeMemoryLayouts.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, andbyteSize().getAsLong() - allocatedBytes() < layout.byteSize()
.IllegalArgumentException
- iflayout.byteSize() != MemoryLayouts.ADDRESS.byteSize()
.
-
allocateArray
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, andbyteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)
.IllegalArgumentException
- ifelementLayout.byteSize()
does not conform to the size of a byte value.
-
allocateArray
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, andbyteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)
.IllegalArgumentException
- ifelementLayout.byteSize()
does not conform to the size of a short value.
-
allocateArray
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, andbyteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)
.IllegalArgumentException
- ifelementLayout.byteSize()
does not conform to the size of a char value.
-
allocateArray
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, andbyteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)
.IllegalArgumentException
- ifelementLayout.byteSize()
does not conform to the size of a int value.
-
allocateArray
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, andbyteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)
.IllegalArgumentException
- ifelementLayout.byteSize()
does not conform to the size of a float value.
-
allocateArray
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, andbyteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)
.IllegalArgumentException
- ifelementLayout.byteSize()
does not conform to the size of a long value.
-
allocateArray
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, andbyteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)
.IllegalArgumentException
- ifelementLayout.byteSize()
does not conform to the size of a double value.
-
allocateArray
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 (seeMemoryLayouts.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, andbyteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * array.length)
.IllegalArgumentException
- iflayout.byteSize() != MemoryLayouts.ADDRESS.byteSize()
.
-
allocate
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, andbyteSize().getAsLong() - allocatedBytes() < layout.byteSize()
.
-
allocateArray
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, andbyteSize().getAsLong() - allocatedBytes() < (elementLayout.byteSize() * count)
.
-
allocate
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 tosize
.- 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, iflimit() - size() < bytesSize
.
-
allocate
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 toalignment
.- 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, iflimit() - 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 interfaceAutoCloseable
-
boundedScope
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
Creates a new unbounded native scope, backed by off-heap memory.- Returns:
- a new unbounded native scope.
-