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

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

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

Состояние выполнения захватывается обработчиком метода вызова вниз при вызове, записывая его в нативный сегмент, предоставленный пользователем обработчику метода вызова вниз. Для этой цели обработчик метода вызова вниз, связанный с этой опцией, будет содержать дополнительный параметр 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 (например, с помощью заглушки обратного вызова).

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

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

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