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

Interface CLinker

public sealed interface CLinker
A C linker implements the C Application Binary Interface (ABI) calling conventions. Instances of this interface can be used to link foreign functions in native libraries that follow the JVM's target platform C ABI.

Linking a foreign function is a process which requires two components: a method type, and a function descriptor. The method type, consists of a set of carrier types, which, together, specify the Java signature which clients must adhere to when calling the underlying foreign function. The function descriptor contains a set of memory layouts which, together, specify the foreign function signature and classification information (via a custom layout attributes, see CLinker.TypeKind), so that linking can take place.

Clients of this API can build function descriptors using the predefined memory layout constants (based on a subset of the built-in types provided by the C language), found in this interface; alternatively, they can also decorate existing value layouts using the required CLinker.TypeKind classification attribute (this can be done using the MemoryLayout.withAttribute(String, Constable) method). A failure to do so might result in linkage errors, given that linking requires additional classification information to determine, for instance, how arguments should be loaded into registers during a foreign function call.

Implementations of this interface support the following primitive carrier types: byte, short, char, int, long, float, and double, as well as MemoryAddress for passing pointers, and MemorySegment for passing structs and unions. Finally, the CLinker.VaList carrier type can be used to match the native va_list type.

For the linking process to be successful, some requirements must be satisfied; if M and F are the method type (obtained after dropping any prefix arguments) and the function descriptor, respectively, used during the linking process, then it must be that:

  • The arity of M is the same as that of F;
  • If the return type of M is void, then F should have no return layout (see FunctionDescriptor.ofVoid(MemoryLayout...));
  • for each pair of carrier type C and layout L in M and F, respectively, where C and L refer to the same argument, or to the return value, the following conditions must hold:
    • If C is a primitve type, then L must be a ValueLayout, and the size of the layout must match that of the carrier type (see Integer.SIZE and similar fields in other primitive wrapper classes);
    • If C is MemoryAddress.class, then L must be a ValueLayout, and its size must match the platform's address size (see MemoryLayouts.ADDRESS). For this purpose, the C_POINTER layout constant can be used;
    • If C is MemorySegment.class, then L must be a GroupLayout
    • If C is VaList.class, then L must be C_VA_LIST

Variadic functions, declared in C either with a trailing ellipses (...) at the end of the formal parameter list or with an empty formal parameter list, are not supported directly. It is not possible to create a method handle that takes a variable number of arguments, and neither is it possible to create an upcall stub wrapping a method handle that accepts a variable number of arguments. However, for downcalls only, it is possible to link a native variadic function by using a specialized method type and function descriptor: for each argument that is to be passed as a variadic argument, an explicit, additional, carrier type and memory layout must be present in the method type and function descriptor objects passed to the linker. Furthermore, as memory layouts corresponding to variadic arguments in a function descriptor must contain additional classification information, it is required that asVarArg(MemoryLayout) is used to create the memory layouts for each parameter corresponding to a variadic argument in a specialized function descriptor.

On unsupported platforms this class will fail to initialize with an ExceptionInInitializerError.

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.

Implementation Requirements:
Implementations of this interface are immutable, thread-safe and value-based.

  • Field Details

    • C_CHAR

      static final ValueLayout C_CHAR
      The layout for the char C type

    • C_SHORT

      static final ValueLayout C_SHORT
      The layout for the short C type

    • C_INT

      static final ValueLayout C_INT
      The layout for the int C type

    • C_LONG

      static final ValueLayout C_LONG
      The layout for the long C type

    • C_LONG_LONG

      static final ValueLayout C_LONG_LONG
      The layout for the long long C type.

    • C_FLOAT

      static final ValueLayout C_FLOAT
      The layout for the float C type

    • C_DOUBLE

      static final ValueLayout C_DOUBLE
      The layout for the double C type

    • C_POINTER

      static final ValueLayout C_POINTER
      The T* native type.

    • C_VA_LIST

      static final MemoryLayout C_VA_LIST
      The layout for the va_list C type

  • Method Details

    • getInstance

      static CLinker getInstance()
      Returns the C linker for the current platform.

      This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

      Returns:
      a linker for this system.
      Throws:
      IllegalCallerException - if access to this method occurs from a module M and the command line option --enable-native-access is either absent, or does not mention the module name M, or ALL-UNNAMED in case M is an unnamed module.

    • systemLookup

      static SymbolLookup systemLookup()
      Obtains a system lookup which is suitable to find symbols in the standard C libraries. The set of symbols available for lookup is unspecified, as it depends on the platform and on the operating system.

      This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

      Returns:
      a system-specific library lookup which is suitable to find symbols in the standard C libraries.
      Throws:
      IllegalCallerException - if access to this method occurs from a module M and the command line option --enable-native-access is either absent, or does not mention the module name M, or ALL-UNNAMED in case M is an unnamed module.

    • downcallHandle

      MethodHandle downcallHandle(Addressable symbol, MethodType type, FunctionDescriptor function)
      Obtains a foreign method handle, with the given type and featuring the given function descriptor, which can be used to call a target foreign function at the given address.

      If the provided method type's return type is MemorySegment, then the resulting method handle features an additional prefix parameter, of type SegmentAllocator, which will be used by the linker runtime to allocate structs returned by-value.

      Parameters:
      symbol - downcall symbol.
      type - the method type.
      function - the function descriptor.
      Returns:
      the downcall method handle.
      Throws:
      IllegalArgumentException - in the case of a method type and function descriptor mismatch, or if the symbol is MemoryAddress.NULL
      See Also:

    • downcallHandle

      MethodHandle downcallHandle(Addressable symbol, SegmentAllocator allocator, MethodType type, FunctionDescriptor function)
      Obtain a foreign method handle, with the given type and featuring the given function descriptor, which can be used to call a target foreign function at the given address.

      If the provided method type's return type is MemorySegment, then the provided allocator will be used by the linker runtime to allocate structs returned by-value.

      Parameters:
      symbol - downcall symbol.
      allocator - the segment allocator.
      type - the method type.
      function - the function descriptor.
      Returns:
      the downcall method handle.
      Throws:
      IllegalArgumentException - in the case of a method type and function descriptor mismatch, or if the symbol is MemoryAddress.NULL
      See Also:

    • downcallHandle

      MethodHandle downcallHandle(MethodType type, FunctionDescriptor function)
      Obtains a foreign method handle, with the given type and featuring the given function descriptor, which can be used to call a target foreign function at an address. The resulting method handle features a prefix parameter (as the first parameter) corresponding to the address, of type Addressable.

      If the provided method type's return type is MemorySegment, then the resulting method handle features an additional prefix parameter (inserted immediately after the address parameter), of type SegmentAllocator), which will be used by the linker runtime to allocate structs returned by-value.

      The returned method handle will throw an IllegalArgumentException if the target address passed to it is MemoryAddress.NULL, or a NullPointerException if the target address is null.

      Parameters:
      type - the method type.
      function - the function descriptor.
      Returns:
      the downcall method handle.
      Throws:
      IllegalArgumentException - in the case of a method type and function descriptor mismatch.
      See Also:

    • upcallStub

      MemoryAddress upcallStub(MethodHandle target, FunctionDescriptor function, ResourceScope scope)
      Allocates a native stub with given scope which can be passed to other foreign functions (as a function pointer); calling such a function pointer from native code will result in the execution of the provided method handle.

      The returned memory address is associated with the provided scope. When such scope is closed, the corresponding native stub will be deallocated.

      The target method handle should not throw any exceptions. If the target method handle does throw an exception, the VM will exit with a non-zero exit code. To avoid the VM aborting due to an uncaught exception, clients could wrap all code in the target method handle in a try/catch block that catches any Throwable, for instance by using the MethodHandles.catchException(MethodHandle, Class, MethodHandle) method handle combinator, and handle exceptions as desired in the corresponding catch block.

      Parameters:
      target - the target method handle.
      function - the function descriptor.
      scope - the upcall stub scope.
      Returns:
      the native stub segment.
      Throws:
      IllegalArgumentException - if the target's method type and the function descriptor mismatch.
      IllegalStateException - if scope has been already closed, or if access occurs from a thread other than the thread owning scope.

    • asVarArg

      static <T extends MemoryLayout> T asVarArg(T layout)
      Returns a memory layout that is suitable to use as the layout for variadic arguments in a specialized function descriptor.
      Type Parameters:
      T - the memory layout type
      Parameters:
      layout - the layout the adapt
      Returns:
      a potentially newly created layout with the right attributes

    • toCString

      static MemorySegment toCString(String str, SegmentAllocator allocator)
      Converts a Java string into a UTF-8 encoded, null-terminated C string, storing the result into a native memory segment allocated using the provided allocator.

      This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement byte array. The CharsetEncoder class should be used when more control over the encoding process is required.

      Parameters:
      str - the Java string to be converted into a C string.
      allocator - the allocator to be used for the native segment allocation.
      Returns:
      a new native memory segment containing the converted C string.

    • toCString

      static MemorySegment toCString(String str, ResourceScope scope)
      Converts a Java string into a UTF-8 encoded, null-terminated C string, storing the result into a native memory segment associated with the provided resource scope.

      This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement byte array. The CharsetEncoder class should be used when more control over the encoding process is required.

      Parameters:
      str - the Java string to be converted into a C string.
      scope - the resource scope to be associated with the returned segment.
      Returns:
      a new native memory segment containing the converted C string.
      Throws:
      IllegalStateException - if scope has been already closed, or if access occurs from a thread other than the thread owning scope.

    • toJavaString

      static String toJavaString(MemoryAddress addr)
      Converts a UTF-8 encoded, null-terminated C string stored at given address into a Java string.

      This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement string. The CharsetDecoder class should be used when more control over the decoding process is required.

      This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

      Parameters:
      addr - the address at which the string is stored.
      Returns:
      a Java string with the contents of the null-terminated C string at given address.
      Throws:
      IllegalArgumentException - if the size of the native string is greater than the largest string supported by the platform, or if addr == MemoryAddress.NULL.
      IllegalCallerException - if access to this method occurs from a module M and the command line option --enable-native-access is either absent, or does not mention the module name M, or ALL-UNNAMED in case M is an unnamed module.

    • toJavaString

      static String toJavaString(MemorySegment addr)
      Converts a UTF-8 encoded, null-terminated C string stored at given address into a Java string.

      This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement string. The CharsetDecoder class should be used when more control over the decoding process is required.

      Parameters:
      addr - the address at which the string is stored.
      Returns:
      a Java string with the contents of the null-terminated C string at given address.
      Throws:
      IllegalArgumentException - if the size of the native string is greater than the largest string supported by the platform.
      IllegalStateException - if the size of the native string is greater than the size of the segment associated with addr, or if addr is associated with a segment that is not alive.

    • allocateMemory

      static MemoryAddress allocateMemory(long size)
      Allocates memory of given size using malloc.

      This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

      Parameters:
      size - memory size to be allocated
      Returns:
      addr memory address of the allocated memory
      Throws:
      OutOfMemoryError - if malloc could not allocate the required amount of native memory.
      IllegalCallerException - if access to this method occurs from a module M and the command line option --enable-native-access is either absent, or does not mention the module name M, or ALL-UNNAMED in case M is an unnamed module.

    • freeMemory

      static void freeMemory(MemoryAddress addr)
      Frees the memory pointed by the given memory address.

      This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

      Parameters:
      addr - memory address of the native memory to be freed
      Throws:
      IllegalCallerException - if access to this method occurs from a module M and the command line option
      IllegalArgumentException - if addr == MemoryAddress.NULL. --enable-native-access is either absent, or does not mention the module name M, or ALL-UNNAMED in case M is an unnamed module.