Интерфейс Linker.Option

Значение index должно соответствовать 0 <= index <= N, где N — количество компоновок аргументов дескриптора функции, используемого вместе с этим параметром компоновщика. Если index равно:

• 0, все аргументы, передаваемые функции, передаются как аргументы переменной длины
• N, ни один из аргументов, передаваемых функции, не передается как аргумент переменной длины
• m, где 0 < m < N, аргументы m..N-1 передаются как аргументы переменной длины

Состояние выполнения захватывается дескриптором метода downcall при вызове путем записи в нативный сегмент, предоставленный пользователем дескриптору метода downcall. Для этого дескриптор метода downcall, связанный с данным параметром, будет иметь дополнительный параметр типа MemorySegment, непосредственно следующий за целевым адресом и необязательными параметрами типа SegmentAllocator. Этот параметр, сегмент состояния вызова, представляет собой нативный сегмент, в который записывается захваченное состояние.

Размер и выравнивание сегмента состояния вызова должны быть совместимы с компоновкой, возвращаемой методом captureStateLayout(). Эта компоновка представляет собой компоновку структуры с именованным полем для каждого захваченного значения.

Захваченное состояние можно получить из сегмента состояния вызова, создав дескрипторы переменных на основе компоновки состояния вызова.

В следующем примере показано использование этого параметра компоновщика:

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, 0L);
    // use errno
}

Компоновка состояния вызова зависит от платформы, но гарантированно является компоновкой структуры, содержащей только компоновки значений и, возможно, компоновки заполнения. Например, в Windows возвращаемая компоновка может содержать три компоновки значений с именами:

• GetLastError
• WSAGetLastError
• errno

Клиенты могут получить имена поддерживаемых компоновок захватываемых значений следующим образом:

   List<String> capturedNames = Linker.Option.captureStateLayout().memberLayouts().stream()
       .map(MemoryLayout::name)
       .flatMap(Optional::stream)
       .toList();

Критическая функция — это функция, время выполнения которой во всех случаях крайне мало (сопоставимо с вызовом пустой функции) и которая не выполняет обратный вызов Java (например, используя заглушку upcall).

Использование этого параметра компоновщика служит подсказкой, которую некоторые реализации могут применять для выполнения оптимизаций, допустимых только для критических функций.

Использование этого параметра компоновщика при компоновке некритических функций, вероятно, приведет к нежелательным последствиям, таким как снижение производительности или сбои JVM.

Критические функции могут при необходимости получать доступ к куче Java. Это позволяет клиентам передавать сегменты памяти в куче в качестве адресов, хотя обычно допустимы только сегменты памяти вне кучи. Область памяти в куче Java доступна через временный нативный адрес, действительный в течение вызова функции. Поэтому этот механизм рекомендуется использовать только в тех случаях, когда функции требуется кратковременный доступ к памяти кучи Java, а копирование необходимых данных в сегмент памяти вне кучи было бы неприемлемым с точки зрения производительности.