Интерфейс 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);
    // use errno
}

Макет состояния захвата зависит от платформы, но гарантированно является макетом структуры^{ПРЕДПРОСМОТР}, содержащим только макеты значений^{ПРЕДПРОСМОТР} и, возможно, макеты заполнения^{ПРЕДПРОСМОТР}. Например, на Windows возвращаемый макет может содержать три макета значений с именами:

• GetLastError
• WSAGetLastError
• errno

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

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

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

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

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