public static sealed interface Linker.Option
Option is a preview API of the Java platform. | Modifier and Type | Method | Description |
|---|---|---|
static Linker.OptionPREVIEW |
captureCallState |
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 |
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. |
static Linker.OptionPREVIEW |
isTrivial() |
Returns a linker option used to mark a foreign function as trivial. |
static Linker.OptionPREVIEW firstVariadicArg(int index)
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 argumentsN, none of the arguments passed to the function are passed as variadic argumentsn, where 0 < m < N, the arguments m..N are passed as variadic argumentsindex - the index of the first variadic argument layout in the function descriptor associated with a downcall linkage request.static Linker.OptionPREVIEW captureCallState(String... capturedState)
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 this option will feature an additional MemorySegmentPREVIEW parameter directly following the target address, and optional SegmentAllocatorPREVIEW parameters. This parameter, the capture state segment, represents the native segment into which the captured state is written.
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 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.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);
// use errno
}
capturedState - the names of the values to save.IllegalArgumentException - if at least one of the provided capturedState names is unsupported on the current platform.static StructLayoutPREVIEW captureStateLayout()
captureCallState(String...). The capture state layout is platform-dependent but is guaranteed to be a struct layoutPREVIEW containing only value layoutsPREVIEW and possibly padding layoutsPREVIEW. As an example, on Windows, the returned layout might contain three value layouts named:
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();
captureCallState(String...)
static Linker.OptionPREVIEW isTrivial()
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.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/Linker.Option.html
Optionwhen preview features are enabled.