Module java.base
Package java.lang.foreign

# Interface Linker.Option

All Known Subinterfaces:
  `Linker.Option.CaptureCallStatePREVIEW`

Enclosing interface:
  `LinkerPREVIEW`

public static sealed interface Linker.Option permits Linker.Option.CaptureCallStatePREVIEW (not exhaustive)
`Option` is a preview API of the Java platform.
Programs can only use `Option` 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 is used to indicate additional linking requirements to the linker, besides what is described by a function descriptor.

Since:
  20

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `Linker.Option.CaptureCallStatePREVIEW`
  Preview.
  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.

- ## Method Summary

  Static Methods
  Modifier and Type
  Method
  Description
  `static Linker.Option.CaptureCallStatePREVIEW`
  `captureCallState(String... capturedState)`
  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 Linker.OptionPREVIEW`
  `firstVariadicArg(int index)`
  Returns a linker option used to denote the index of the first variadic argument layout in a foreign function call.

- ## Method Details

  - ### firstVariadicArg

    static Linker.OptionPREVIEW firstVariadicArg(int index)
    Returns a linker option used to denote the index of the first variadic argument layout in a foreign function call.
    Parameters:
      `index` - the index of the first variadic argument in a downcall handle linkage request.
    Returns:
      a linker option used to denote the index of the first variadic argument layout in a foreign function call

  - ### captureCallState

    static Linker.Option.CaptureCallStatePREVIEW captureCallState(String... capturedState)
    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.

    A downcall method handle linked with this option will feature an additional `MemorySegment`PREVIEW parameter directly following the target address, and optional `SegmentAllocator`PREVIEW parameters. This memory segment must be a native segment into which the captured state is written.

    Parameters:
      `capturedState` - the names of the values to save.
    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
    See Also:
      - `Linker.Option.CaptureCallState.supported()`PREVIEW