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.