Module java.base
Package java.lang.foreign

Interface Linker.Option

封闭接口：
Linker预览
public static sealed interface Linker.Option
Option 是 Java 平台的预览 API。
仅当启用预览功能时，程序才能使用 Option。
预览功能可能会在将来的版本中被移除，或升级为 Java 平台的永久功能。
链接器选项用于向链接请求提供附加参数。
自：
20

  • Method Details

    • firstVariadicArg

      static Linker.OptionPREVIEW firstVariadicArg(int index)
      返回一个链接器选项，用于表示指示与 downcall 链接请求关联的函数描述符描述的函数的可变参数的起始索引。

      index 值必须符合 0 <= index <= N，其中 N 是与此链接器选项一起使用的函数描述符的参数布局数量。当 index 为：

      • 0，所有传递给函数的参数都作为可变参数传递
      • N，传递给函数的参数都不作为可变参数传递
      • n，其中 0 < m < N，参数 m..N 作为可变参数传递
      在链接可变参数函数时，始终使用此链接器选项是很重要的，即使没有传递可变参数（列表中的第二种情况），因为这可能仍会影响某些平台上的调用约定。
      实现注意：
      当进行链接请求时，即函数描述符可用时，将验证索引值。
      参数：
      index - 与 downcall 链接请求关联的函数描述符中第一个可变参数布局的索引。
      返回：
      一个链接器选项，用于表示指示与 downcall 链接请求关联的函数描述符描述的函数的可变参数的起始索引

    • captureCallState

      static Linker.OptionPREVIEW captureCallState(String... capturedState)
      返回一个链接器选项，用于在调用与 downcall 方法句柄关联的外部函数后立即保存执行状态的部分，以防被 Java 运行时覆盖，或通过常规方式读取。

      执行状态在调用 downcall 方法句柄时通过写入到由用户提供给 downcall 方法句柄的本机段来捕获。为此，使用此选项链接的 downcall 方法句柄将在目标地址之后直接包含一个额外的 MemorySegment预览 参数，并可选的 SegmentAllocator预览 参数。这个参数，即捕获状态段，表示被捕获状态写入的本机段。

      捕获的状态段必须具有与 captureStateLayout() 返回的布局兼容的大小和对齐方式。此布局是一个结构布局，每个捕获值都有一个命名字段。

      可以通过从 captureStateLayout() 构造 var 句柄来从捕获状态段中检索捕获的状态。

      以下示例演示了此链接器选项的使用：

      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);
    // 使用 errno
}
      参数：
      capturedState - 要保存的值的名称。
      返回：
      一个链接器选项，用于在调用与 downcall 方法句柄关联的外部函数后立即保存执行状态的部分，以防被 Java 运行时覆盖，或通过常规方式读取
      抛出：
      IllegalArgumentException - 如果提供的至少一个 capturedState 名称在当前平台上不受支持。
      参见：

    • captureStateLayout

      static StructLayoutPREVIEW captureStateLayout()
      返回一个表示传递给与 captureCallState(String...) 链接的 downcall 句柄的捕获状态段布局的结构布局。

      捕获状态布局是平台相关的，但保证是一个包含仅 value layouts预览 和可能包含 padding layouts预览 的 struct layout预览。例如，在 Windows 上，返回的布局可能包含三个命名为的 value layouts：

      • GetLastError
      • WSAGetLastError
      • errno

      客户端可以按如下方式获取支持的捕获值布局的名称：

         List<String> capturedNames = Linker.Option.captureStateLayout().memberLayouts().stream()
       .map(MemoryLayout::name)
       .flatMap(Optional::stream)
       .toList();
      返回：
      一个表示传递给与 captureCallState(String...) 链接的 downcall 句柄的捕获状态段布局的结构布局
      参见：

    • isTrivial

      static Linker.OptionPREVIEW isTrivial()
      返回一个链接器选项，用于标记外部函数为平凡的。

      平凡函数是在所有情况下运行时间极短的函数（类似于调用空函数），并且不会回调到 Java（例如使用 upcall stub）。

      使用此链接器选项是一种提示，某些实现可能会使用它来应用仅对平凡函数有效的优化。

      在链接非平凡函数时使用此链接器选项可能会产生不良影响，例如性能损失或 JVM 崩溃。

      返回：
      一个链接器选项，用于标记外部函数为平凡的