Interface Linker.Option

The index value must conform to 0 <= index <= N, where N is the number of argument layouts of the function descriptor used in conjunction with this linker option. When the index 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, where 0 < m < N, the arguments m..N-1 are passed as variadic arguments

Execution state is initialized from, or saved to a native segment provided by the user to the downcall method handle. For this purpose, a downcall method handle linked with this option will feature an additional MemorySegment parameter directly following the target address, and optional SegmentAllocator parameters. This parameter, the capture state segment, represents the native segment from which the capture state is initialized, and into which the capture state is saved.

The capture state segment must have size and alignment compatible with the layout returned by captureStateLayout(). This layout is a struct layout which has a named field for each captured value.

Captured state can be stored in, or retrieved from the capture state segment by constructing var handles from the capture state layout. Some functions require this state to be initialized to a particular value before invoking the downcall.

The following example demonstrates the use of this linker option:

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);
    errnoHandle.set(capturedState, 0L, 0); // set errno to 0
    handle.invoke(capturedState);
    int errno = (int) errnoHandle.get(capturedState, 0L);
    // use errno
}

The capture state layout is platform-dependent but is guaranteed to be a struct layout containing only value layouts and possibly padding 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:

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

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

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

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

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