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

Interface CLinker

public 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 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.

API Note:
In the future, if the Java language permits, CLinker may become a sealed interface, which would prohibit subclassing except by explicitly permitted types.
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 method 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:
      IllegalAccessError - if the runtime property foreign.restricted is not set to either permit, warn or debug (the default value is set to deny).

    • downcallHandle

      MethodHandle downcallHandle​(Addressable symbol, MethodType type, FunctionDescriptor function)
      Obtain a foreign method handle, with given type, which can be used to call a target foreign function at a given address and featuring a given function descriptor.
      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.
      See Also:
      LibraryLookup.lookup(String)

    • upcallStub

      MemorySegment upcallStub​(MethodHandle target, FunctionDescriptor function)
      Allocates a native segment whose base address (see MemorySegment.address()) 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 segment is shared, and it only features the MemorySegment.CLOSE access mode. When the returned segment is closed, the corresponding native stub will be deallocated.

      Parameters:
      target - the target method handle.
      function - the function descriptor.
      Returns:
      the native stub segment.
      Throws:
      IllegalArgumentException - if the target's method type and the function descriptor mismatch.

    • 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)
      Converts a Java string into a null-terminated C string, using the platform's default charset, storing the result into a new native memory segment.

      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.
      Returns:
      a new native memory segment containing the converted C string.

    • toCString

      static MemorySegment toCString​(String str, Charset charset)
      Converts a Java string into a null-terminated C string, using the given charset, storing the result into a new native memory segment.

      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.
      charset - The Charset to be used to compute the contents of the C string.
      Returns:
      a new native memory segment containing the converted C string.

    • toCString

      static MemorySegment toCString​(String str, NativeScope scope)
      Converts a Java string into a null-terminated C string, using the platform's default charset, storing the result into a native memory segment allocated using the provided 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 scope 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, Charset charset, NativeScope scope)
      Converts a Java string into a null-terminated C string, using the given charset, storing the result into a new native memory segment native memory segment allocated using the provided 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.
      charset - The Charset to be used to compute the contents of the C string.
      scope - the scope to be used for the native segment allocation.
      Returns:
      a new native memory segment containing the converted C string.

    • toJavaStringRestricted

      static String toJavaStringRestricted​(MemoryAddress addr)
      Converts a null-terminated C string stored at given address into a Java string, using the platform's default charset.

      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 method 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.

    • toJavaStringRestricted

      static String toJavaStringRestricted​(MemoryAddress addr, Charset charset)
      Converts a null-terminated C string stored at given address into a Java string, using the given charset.

      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 method 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.
      charset - The Charset to be used to compute the contents of the Java string.
      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.

    • toJavaString

      static String toJavaString​(MemorySegment addr)
      Converts a null-terminated C string stored at given address into a Java string, using the platform's default charset.

      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.

    • toJavaString

      static String toJavaString​(MemorySegment addr, Charset charset)
      Converts a null-terminated C string stored at given address into a Java string, using the given charset.

      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.
      charset - The Charset to be used to compute the contents of the Java string.
      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.

    • allocateMemoryRestricted

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

      This method is restricted. Restricted method 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.

    • freeMemoryRestricted

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

      This method is restricted. Restricted method 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