Module java.base
Package java.foreign

Interface Scope

All Superinterfaces:
AutoCloseable

public interface Scope
extends AutoCloseable
A scope models a unit of resource lifecycle management. It provides primitives for memory allocation, as well as a basic ownership model for allocating resources (e.g. pointers). Each scope has a parent scope (except the global scope, which acts as root of the ownership model).

A scope supports two terminal operation: first, a scope can be closed (see close()), which implies that all resources associated with that scope can be reclaimed; secondly, a scope can be merged into the parent scope (see merge()). After a terminal operation, a scope will no longer be available for allocation.

Scope supports the AutoCloseable interface which enables thread-confided scopes to be used in conjunction with the try-with-resources construct.

  • Method Summary

    Modifier and Type Method Description
    default Pointer<?> allocate​(Layout type)
    Allocate region of memory with given layout.
    <X> Pointer<X> allocate​(LayoutType<X> type)
    Allocate region of memory with given LayoutType.
    default <X> Pointer<X> allocate​(LayoutType<X> elementType, long size)
    Allocate region of memory as an array of elements with given LayoutType.
    default Array<?> allocateArray​(Layout elementType, int size)
    Allocate region of memory as an array of elements with given layout.
    <X> Array<X> allocateArray​(LayoutType<X> elementType, long size)
    Allocate region of memory as an array of elements with given LayoutType.
    default <X> Array<X> allocateArray​(LayoutType<X> elementType, Object init)
    Allocate region of memory as an array of elements with given LayoutType.
    <T> Callback<T> allocateCallback​(Class<T> funcIntfClass, T funcIntfInstance)
    Allocate a function pointer backed by given Java functional interface instance.
    <T> Callback<T> allocateCallback​(T funcIntfInstance)
    Allocate a function pointer backed by given Java functional interface instance.
    default Pointer<Byte> allocateCString​(String str)
    Allocate and initialize a region of memory with given string.
    <T extends Struct<T>>
    T
    allocateStruct​(Class<T> carrier)
    Allocate region of memory with given data.
    void close()
    Closes this scope.
    Scope fork()
    Create a scope whose parent is the current scope.
    static Scope globalScope()
    Retrieves the global scope associated with this VM.
    void merge()
    Copies all resources of this scope to the parent scope.
    static Scope newNativeScope()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Scope parent()
    The parent of this scope.
  • Method Details

    • allocate

      <X> Pointer<X> allocate​(LayoutType<X> type)
      Allocate region of memory with given LayoutType.
      Type Parameters:
      X - the carrier type associated with the memory region to be allocated.
      Parameters:
      type - the LayoutType.
      Returns:
      a pointer to the newly allocated memory region.
    • allocate

      default Pointer<?> allocate​(Layout type)
      Allocate region of memory with given layout.
      Parameters:
      type - the layout.
      Returns:
      a pointer to the newly allocated memory region.
    • allocate

      default <X> Pointer<X> allocate​(LayoutType<X> elementType, long size)
      Allocate region of memory as an array of elements with given LayoutType. This is effectively the same as:

      allocateArray(type, size).elementPointer()

      Type Parameters:
      X - the carrier type associated with the element type of the array to be allocated.
      Parameters:
      elementType - the LayoutType of the array element.
      size - the array size.
      Returns:
      a pointer to the first element of the array.
    • allocateArray

      <X> Array<X> allocateArray​(LayoutType<X> elementType, long size)
      Allocate region of memory as an array of elements with given LayoutType. This is effectively the same as:

      allocate(elementType.array(size)).withLimit()

      Type Parameters:
      X - the carrier type associated with the element type of the array to be allocated.
      Parameters:
      elementType - the LayoutType of the array element.
      size - the array size.
      Returns:
      an array to the first element of the array.
    • allocateArray

      default Array<?> allocateArray​(Layout elementType, int size)
      Allocate region of memory as an array of elements with given layout. The resulting pointer will have no carrier information associated with it. This is effectively the same as:

      allocate(LayoutType.ofVoid(elementType).array(size)).withLimit();

      Parameters:
      elementType - the LayoutType of the array element.
      size - the array size.
      Returns:
      an array to the first element of the array.
    • allocateArray

      default <X> Array<X> allocateArray​(LayoutType<X> elementType, Object init) throws IllegalArgumentException
      Allocate region of memory as an array of elements with given LayoutType. The array is initialized with the contents of a given Java array.
      Type Parameters:
      X - the carrier type associated with the element type of the array to be allocated.
      Parameters:
      elementType - the LayoutType of the array element.
      init - the (Java) array initializer.
      Returns:
      an array to the first element of the array.
      Throws:
      IllegalArgumentException - if the array initializer type is not compatible with the required type.
    • allocateStruct

      <T extends Struct<T>> T allocateStruct​(Class<T> carrier)
      Allocate region of memory with given data.
      Type Parameters:
      T - the carrier type.
      Parameters:
      carrier - the carrier type modelling the data.
      Returns:
      a new struct instance (of type Struct).
      See Also:
      Struct
    • allocateCallback

      <T> Callback<T> allocateCallback​(Class<T> funcIntfClass, T funcIntfInstance) throws IllegalArgumentException
      Allocate a function pointer backed by given Java functional interface instance.
      Type Parameters:
      T - the carrier type.
      Parameters:
      funcIntfClass - a functional interface class annotated with the NativeCallback annotation.
      funcIntfInstance - an instance of a functional interface.
      Returns:
      a new function pointer (of type Scope).
      Throws:
      IllegalArgumentException - if the provided class is not annotated with the NativeCallback annotation.
    • allocateCallback

      <T> Callback<T> allocateCallback​(T funcIntfInstance)
      Allocate a function pointer backed by given Java functional interface instance. This method is equivalent to:

      allocateCallback(inferClass(funcIntfInstance), funcIntfInstance)

      Where the inferClass is a best-effort attempt at extracting the functional interface from the object passed to this method.
      Type Parameters:
      T - the carrier type.
      Parameters:
      funcIntfInstance - an instance of a functional interface.
      Returns:
      a new function pointer (of type Scope).
      Throws:
      IllegalArgumentException - if no suitable functional interface can be inferred from the provided instance.
    • allocateCString

      default Pointer<Byte> allocateCString​(String str)
      Allocate and initialize a region of memory with given string. Note: this routine adds a terminator to the string meaning that if the input string contain N characters, the size of the allocated region would be N + 1.
      Parameters:
      str - the string to be allocated.
      Returns:
      a pointer to the newly allocated memory region.
    • parent

      Scope parent()
      The parent of this scope.
      Returns:
      the parent of this scope.
    • close

      void close()
      Closes this scope. All associated resources will be freed as a result of this operation. Any existing resources (e.g. pointers) associated with this scope will no longer be accessible. As this is a terminal operation, this scope will no longer be available for further allocation.
      Specified by:
      close in interface AutoCloseable
    • merge

      void merge()
      Copies all resources of this scope to the parent scope. As this is a terminal operation, this scope will no longer be available for further allocation.
    • fork

      Scope fork()
      Create a scope whose parent is the current scope.
      Returns:
      the new scope.
    • globalScope

      static Scope globalScope()
      Retrieves the global scope associated with this VM.
      Returns:
      the global scope.
    • newNativeScope

      @Deprecated(forRemoval=true) static Scope newNativeScope()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Creates a new child of the global scope. This method is equivalent to:

      Scope.globalScope().fork();

      Note: this method will be removed; use globalScope() and fork() instead.
      Returns:
      a new native scope.