Module java.base
Package java.lang.foreign

Interface Linker.Option

Enclosing interface:
LinkerPREVIEW
public static sealed interface Linker.Option
Option is a preview API of the Java platform.
Programs can only use Option when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A linker option is used to indicate additional linking requirements to the linker, besides what is described by a function descriptor.
Since:
20

  • Method Summary

    Static Methods
    Modifier and Type
    Method
    Description
    static Linker.OptionPREVIEW
    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.
    static StructLayoutPREVIEW
    captureStateLayout()
    Returns A struct layout that represents the layout of the capture state segment that is passed to a downcall handle linked with captureCallState(String...).
    static Linker.OptionPREVIEW
    firstVariadicArg(int index)
    Returns a linker option used to denote the index of the first variadic argument layout in a foreign function call.
    static Linker.OptionPREVIEW
    isTrivial()
    Returns A linker option used to mark a foreign function as trivial.

  • Method Details

    • firstVariadicArg

      static Linker.OptionPREVIEW firstVariadicArg(int index)
      Returns a linker option used to denote the index of the first variadic argument layout in a foreign function call.
      Parameters:
      index - the index of the first variadic argument in a downcall handle linkage request.
      Returns:
      a linker option used to denote the index of the first variadic argument layout in a foreign function call

    • captureCallState

      static Linker.OptionPREVIEW 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, by writing it to a native segment provided by the user to the downcall method handle. For this purpose, a downcall method handle linked with the this option will feature an additional MemorySegmentPREVIEW parameter directly following the target address, and optional SegmentAllocatorPREVIEW parameters. This parameter, called the 'capture state segment', represents the native segment into which the captured state is written.

      The capture state segment should have the layout returned by captureStateLayout(). This layout is a struct layout which has a named field for each captured value.

      Captured state can be retrieved from the capture state segment by constructing var handles from the capture state layout.

      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.capturedStateLayout();
VarHandle errnoHandle = capturedStateLayout.varHandle(PathElement.groupElement("errno"));
try (Arena arena = Arena.ofConfined()) {
    MemorySegment capturedState = arena.allocate(capturedStateLayout);
    handle.invoke(capturedState);
    int errno = errnoHandle.get(capturedState);
    // 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
      See Also:

    • captureStateLayout

      static StructLayoutPREVIEW captureStateLayout()
      Returns A struct layout that represents the layout of the capture state segment that is passed to a downcall handle linked with captureCallState(String...).
      Returns:
      A struct layout that represents the layout of the capture state segment that is passed to a downcall handle linked with captureCallState(String...)
      See Also:

    • isTrivial

      static Linker.OptionPREVIEW isTrivial()
      Returns A linker option used to mark a foreign function as trivial.

      A trivial 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 which some implementations may use to apply optimizations that are only valid for trivial functions.

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

      Returns:
      A linker option used to mark a foreign function as trivial