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 `MemorySegment`PREVIEW parameter directly following the target address, and optional `SegmentAllocator`PREVIEW 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