Module java.base
Package java.lang.foreign

Interface Linker.Option.CaptureCallState

All Superinterfaces:
Linker.OptionPREVIEW
Enclosing interface:
Linker.OptionPREVIEW
public static sealed interface Linker.Option.CaptureCallState extends Linker.OptionPREVIEW
CaptureCallState is a preview API of the Java platform.
Programs can only use CaptureCallState 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 for saving portions of the execution state immediately after calling a foreign function associated with a downcall method handle, before it can be overwritten by the 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 Linker.Option.captureCallState(String[])PREVIEW option will feature an additional MemorySegmentPREVIEW parameter directly following the target address, and optional SegmentAllocatorPREVIEW parameters. This parameter represents the native segment into which the captured state is written.

The native segment should have the layout associated with the particular CaptureCallState instance used to link the downcall handle.

Captured state can be retrieved from this native segment by constructing var handles from the layout associated with the CaptureCallState instance.

The following example demonstrates the use of this linker option: 

MemorySegment targetAddress = ...
CaptureCallState ccs = Linker.Option.captureCallState("errno");
MethodHandle handle = Linker.nativeLinker().downcallHandle(targetAddress, FunctionDescriptor.ofVoid(), ccs);

VarHandle errnoHandle = ccs.layout().varHandle(PathElement.groupElement("errno"));
try (Arena arena = Arena.openConfined()) {
    MemorySegment capturedState = arena.allocate(ccs.layout());
    handle.invoke(capturedState);
    int errno = errnoHandle.get(capturedState);
    // use errno
}

  • Nested Class Summary

    Nested classes/interfaces declared in interface java.lang.foreign.Linker.OptionPREVIEW

    Linker.Option.CaptureCallStatePREVIEW

  • Method Summary

    Modifier and Type
    Method
    Description
    StructLayoutPREVIEW
    layout()
    Returns A struct layout that represents the layout of the native segment passed to a downcall handle linked with this CapturedCallState instance.
    static Set<String>
    supported()
    Returns the names of the state that can be capture by this implementation.

  • Method Details

    • layout

      StructLayoutPREVIEW layout()
      Returns A struct layout that represents the layout of the native segment passed to a downcall handle linked with this CapturedCallState instance.
      Returns:
      A struct layout that represents the layout of the native segment passed to a downcall handle linked with this CapturedCallState instance

    • supported

      static Set<String> supported()
      Returns the names of the state that can be capture by this implementation.
      Returns:
      the names of the state that can be capture by this implementation