public static sealed interface Linker.Option
Option
是 Java 平台的预览 API。
预览功能可能会在将来的版本中被移除,或升级为 Java 平台的永久功能。
链接器选项用于向链接请求提供附加参数。
- 自:
- 20
-
Method Summary
Static MethodsModifier and TypeMethodDescriptionstatic Linker.OptionPREVIEW
captureCallState
(String... capturedState) 返回一个链接器选项,用于在调用与 downcall 方法句柄关联的外部函数后立即保存执行状态的部分,以防被 Java 运行时覆盖,或通过常规方式读取。static StructLayoutPREVIEW
返回一个表示传递给与captureCallState(String...)
链接的 downcall 句柄的捕获状态段布局的结构布局。static Linker.OptionPREVIEW
firstVariadicArg
(int index) 返回一个链接器选项,用于表示指示与 downcall 链接请求关联的函数描述符描述的函数的可变参数的起始索引。static Linker.OptionPREVIEW
返回一个链接器选项,用于标记外部函数为平凡的。
-
Method Details
-
firstVariadicArg
返回一个链接器选项,用于表示指示与 downcall 链接请求关联的函数描述符描述的函数的可变参数的起始索引。index
值必须符合0 <= index <= N
,其中N
是与此链接器选项一起使用的函数描述符的参数布局数量。当index
为:0
,所有传递给函数的参数都作为可变参数传递N
,传递给函数的参数都不作为可变参数传递n
,其中0 < m < N
,参数m..N
作为可变参数传递
- 实现注意:
- 当进行链接请求时,即函数描述符可用时,将验证索引值。
- 参数:
-
index
- 与 downcall 链接请求关联的函数描述符中第一个可变参数布局的索引。 - 返回:
- 一个链接器选项,用于表示指示与 downcall 链接请求关联的函数描述符描述的函数的可变参数的起始索引
-
captureCallState
返回一个链接器选项,用于在调用与 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
返回一个表示传递给与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
返回一个链接器选项,用于标记外部函数为平凡的。平凡函数是在所有情况下运行时间极短的函数(类似于调用空函数),并且不会回调到 Java(例如使用 upcall stub)。
使用此链接器选项是一种提示,某些实现可能会使用它来应用仅对平凡函数有效的优化。
在链接非平凡函数时使用此链接器选项可能会产生不良影响,例如性能损失或 JVM 崩溃。
- 返回:
- 一个链接器选项,用于标记外部函数为平凡的
-
Option
。