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

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

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

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

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

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

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

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);
    errnoHandle.set(capturedState, 0L, 0); // set errno to 0
    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 предоставляется через временный native-адрес, действительный на протяжении вызова функции. Поэтому этот механизм рекомендуется использовать только в тех случаях, когда функции требуется кратковременный доступ к памяти кучи Java, а копирование соответствующих данных в сегмент памяти вне кучи слишком сильно сказалось бы на производительности.