Method Summary

Method Details

• firstVariadicArg

  static Linker.Option firstVariadicArg(int index)

  Returns a linker option used to denote the index indicating the start of the variadic arguments passed to the function described by the function descriptor associated with a downcall linkage request.

  Theindex value must conform to0 <= index <= N, whereN is the number of argument layouts of the function descriptor used inconjunction with this linker option. When theindex is:

  • 0, all arguments passed to the function are passed as variadic arguments
  • N, none of the arguments passed to the function are passed as variadic arguments
  • m, where0 < m < N, the argumentsm..N-1 are passed as variadic arguments

  It is important to always use this linker option when linking avariadic function, even if no variadicargument is passed (the second case in the list above), as this might stillaffect the calling convention on certain platforms.

  Implementation Note:

  The index value is validated when making a linkage request, which is when the function descriptor against which the index is validated is available.

  Parameters:

  index - the index of the first variadic argument layout in the function descriptor associated with a downcall linkage request

  Returns:

  a linker option used to denote the index indicating the start of the variadic arguments passed to the function described by the function descriptor associated with a downcall linkage request

• captureCallState

  static Linker.Option captureCallState(String... capturedState)

  Returns a linker option used to save portions of the execution state immediately after calling a foreign function associated with a downcall method handle, before it can be overwritten by the Java runtime, or read through conventional means.

  Execution state is captured by a downcall method handle on invocation, bywriting it to a native segment provided by the user to the downcall methodhandle. For this purpose, a downcall method handle linked with this optionwill feature an additionalMemorySegment parameter directly followingthe target address, and optionalSegmentAllocator parameters. Thisparameter, thecapture state segment, represents the native segmentinto which the captured state is written.

  The capture state segment must have size and alignment compatible with thelayout returned bycaptureStateLayout(). This layout is a structlayout which has a named field for each captured value.

  Captured state can be retrieved from the capture state segment by constructingvar handles from thecapture state layout.

  The following example demonstrates the use of this linker option:

  Copy

  MemorySegment targetAddress = ...Linker.Option ccs = Linker.Option.captureCallState("errno");MethodHandle handle = Linker.nativeLinker().downcallHandle(targetAddress, FunctionDescriptor.ofVoid(), ccs);StructLayout capturedStateLayout = Linker.Option.captureStateLayout();VarHandle errnoHandle = capturedStateLayout.varHandle(PathElement.groupElement("errno"));try (Arena arena = Arena.ofConfined()) {    MemorySegment capturedState = arena.allocate(capturedStateLayout);    handle.invoke(capturedState);    int errno = (int) errnoHandle.get(capturedState, 0L);    // use errno}

  Parameters:

  capturedState - the names of the values to save

  Returns:

  a linker option used to save portions of the execution state immediately after calling a foreign function associated with a downcall method handle, before it can be overwritten by the Java runtime, or read through conventional means

  Throws:

  IllegalArgumentException - if at least one of the providedcapturedState names is unsupported on the current platform

  See Also:

  • captureStateLayout()

• captureStateLayout

  static StructLayout captureStateLayout()

  Returns a struct layout that represents the layout of the capture state segment that is passed to a downcall handle linked withcaptureCallState(String...).

  The capture state layout isplatform-dependent but is guaranteed to beastruct layout containing onlyvalue layoutsand possiblypadding layouts.As an example, on Windows, the returned layout might contain three value layouts named:

  • GetLastError
  • WSAGetLastError
  • errno

  Clients can obtain the names of the supported captured value layouts as follows:

  Copy

     List<String> capturedNames = Linker.Option.captureStateLayout().memberLayouts().stream()       .map(MemoryLayout::name)       .flatMap(Optional::stream)       .toList();

  Returns:

  a struct layout that represents the layout of the capture state segment that is passed to a downcall handle linked withcaptureCallState(String...)

  See Also:

  • captureCallState(String...)

• critical

  static Linker.Option critical(boolean allowHeapAccess)

  Returns a linker option used to mark a foreign function ascritical.

  A critical function is a function that has an extremely short running time inall cases (similar to calling an empty function), and does not call back intoJava (e.g. using an upcall stub).

  Using this linker option is a hint that some implementations may use to applyoptimizations that are only valid for critical functions.

  Using this linker option when linking non-critical functions is likely to haveadverse effects, such as loss of performance or JVM crashes.

  Critical functions can optionally allow access to the Java heap. This allowsclients to pass heap memory segments as addresses, where normally only off-heapmemory segments would be allowed. The memory region inside the Java heap isexposed through a temporary native address that is valid for the duration ofthe function call. Use of this mechanism is therefore only recommended when afunction needs to do short-lived access to Java heap memory, and copying therelevant data to an off-heap memory segment would be prohibitive in terms ofperformance.

  Parameters:

  allowHeapAccess - whether the linked function should allow access to the Java heap.

  Returns:

  a linker option used to mark a foreign function ascritical