Интерфейсный линкер

Внешние функции обычно находятся в библиотеках, которые могут загружаться по требованию. Каждая библиотека соответствует определенному ABI (Application Binary Interface). ABI — это набор соглашений о вызовах и типов данных, связанных с компилятором, ОС и процессором, на которых была построена библиотека. Например, C-компилятор на Linux/x64 обычно создает библиотеки, которые соответствуют ABI SystemV.

Линкер имеет подробные сведения о соглашениях о вызовах и типах данных, используемых конкретным ABI. Для любой библиотеки, которая соответствует этому ABI, линкер может взаимодействовать между кодом Java, выполняемым в JVM, и внешними функциями в библиотеке. В частности:

• Линкер позволяет коду Java связываться с внешними функциями через обработчики вызовов вниз^{ОГРАНИЧЕННО}; и
• Линкер позволяет внешним функциям вызывать обработчики методов Java через создание заглушек для вызовов вверх^{ОГРАНИЧЕННО}.

Кроме того, линкер предоставляет способ поиска внешних функций в библиотеках, соответствующих ABI. Каждый линкер выбирает набор библиотек, которые обычно используются на комбинации ОС и процессора, связанных с ABI. Например, линкер для Linux/x64 может выбрать две библиотеки: libc и libm. Функции в этих библиотеках экспонируются через поиск символов.

Вызов функций нативных функций

size_t strlen(const char *s);

Linker linker = Linker.nativeLinker();
MethodHandle strlen = linker.downcallHandle(
    linker.defaultLookup().findOrThrow("strlen"),
    FunctionDescriptor.of(JAVA_LONG, ADDRESS)
);

 try (Arena arena = Arena.ofConfined()) {
     MemorySegment str = arena.allocateFrom("Hello");
     long len = (long) strlen.invokeExact(str);  // 5
 }

Описание сигнатур C

Скалярные типы C, такие как bool, int, моделируются как представления значений подходящего носителя. отображение между скалярным типом и соответствующим каноническим представлением зависит от ABI, реализованного нативным линком (см. ниже).

Составные типы моделируются как представления групп. Более конкретно, тип C struct сопоставляется с представлением структуры, а тип C union сопоставляется с union layout. При определении представления структуры или объединения клиенты должны учитывать ограничения размера и выравнивания соответствующего определения составного типа в C. Например, отступы между двумя полями структуры должны быть смоделированы явно, добавив член представления заполнения достаточного размера в результирующее представление структуры.

Наконец, типы указателей, такие как int** и int(*)(size_t*, size_t*), моделируются как представления адресов. Когда пространственные границы типа указателя известны статически, представление адреса может быть связано с целевым представлением. Например, указатель, который, как известно, указывает на массив C int[2], может быть смоделирован как представление адреса, целевым представлением которого является последовательное представление, количество элементов которого равно 2, а тип элемента — ValueLayout.JAVA_INT.

Все реализации нативного линкера гарантируют предоставление канонических представлений для следующего набора типов:

• bool
• char
• short
• int
• long
• long long
• float
• double
• size_t
• wchar_t
• void*

Нативный линкер обычно не предоставляет канонических представлений для беззнаковых целочисленных типов C. Вместо этого они моделируются с использованием канонических представлений, связанных с соответствующими знаковыми целочисленными типами. Например, тип C unsigned long отображается на константу представления ValueLayout.JAVA_LONG на Linux/x64, но отображается на константу представления ValueLayout.JAVA_INT на Windows/x64.

Следующая таблица показывает некоторые примеры того, как типы C моделируются на Linux/x64 в соответствии с "System V Application Binary Interface" (все примеры, приведенные здесь, предполагают эти платформенно-зависимые отображения):

Сопоставление типов C

Тип C	Макет	Тип Java
bool	ValueLayout.JAVA_BOOLEAN	boolean
char unsigned char	ValueLayout.JAVA_BYTE	byte
short unsigned short	ValueLayout.JAVA_SHORT	short
int unsigned int	ValueLayout.JAVA_INT	int
long unsigned long	ValueLayout.JAVA_LONG	long
long long unsigned long long	ValueLayout.JAVA_LONG	long
float	ValueLayout.JAVA_FLOAT	float
double	ValueLayout.JAVA_DOUBLE	double
size_t	ValueLayout.JAVA_LONG	long
char*, int**, struct Point*	ValueLayout.ADDRESS	MemorySegment
int (*ptr)[10]	ValueLayout.ADDRESS.withTargetLayout( MemoryLayout.sequenceLayout(10, ValueLayout.JAVA_INT) );	MemorySegment
struct Point { int x; long y; };	MemoryLayout.structLayout( ValueLayout.JAVA_INT.withName("x"), MemoryLayout.paddingLayout(4), ValueLayout.JAVA_LONG.withName("y") );	MemorySegment
union Choice { float a; int b; }	MemoryLayout.unionLayout( ValueLayout.JAVA_FLOAT.withName("a"), ValueLayout.JAVA_INT.withName("b") );	MemorySegment

Модуль связывания с нативным кодом поддерживает только описатели функций, у которых макеты аргументов/возвращаемых значений являются корректными макетами. Более формально, макет `L` корректен, если:

• L является макетом значения, и L получен из канонического макета C таким образом, что L.byteAlignment() <= C.byteAlignment()
• L является макетом последовательности S и все следующие условия выполняются:
  1. L.byteAlignment() равен естественному выравниванию макета последовательности, и
  2. S.elementLayout() является корректным макетом.
• L является макетом группы G и все следующие условия выполняются:
  1. G.byteAlignment() равен естественному выравниванию макета группы
  2. G.byteSize() является кратным G.byteAlignment()
  3. Каждый макет члена в G.memberLayouts() является либо макетом заполнения, либо корректным макетом
  4. Каждый макет не-заполнения E в G.memberLayouts() следует за необязательным макетом заполнения, размер которого — минимально необходимый для выравнивания E
  5. G содержит необязательный макет заполнения в конце, размер которого — минимально необходимый для удовлетворения (2)

Описатель функции является корректным, если её макеты аргументов и возвращаемых значений корректны и не являются макетами последовательностей. Модуль связывания с нативным кодом гарантирует отклонение некорректных описателей функций. Однако модуль связывания с нативным кодом может отклонить и корректные описатели функций согласно правилам, зависящим от платформы. Например, некоторые модули связывания с нативным кодом могут отклонять упакованные макеты структур — макеты структур, макеты членов которых имеют ослабленные ограничения на выравнивание, чтобы избежать вставки дополнительного заполнения.

Функции-указатели

void qsort(void *base, size_t nmemb, size_t size,
           int (*compar)(const void *, const void *));

Linker linker = Linker.nativeLinker();
MethodHandle qsort = linker.downcallHandle(
    linker.defaultLookup().findOrThrow("qsort"),
        FunctionDescriptor.ofVoid(ADDRESS, JAVA_LONG, JAVA_LONG, ADDRESS)
);

Для вызова дескриптора вызова вниз qsort, полученного выше, нам нужен указатель на функцию, который передаётся в качестве последнего параметра. То есть нам нужно создать указатель на функцию из существующего дескриптора метода. Сначала напишем метод Java, который может сравнивать два целочисленных элемента, переданных как указатели (т. е. как сегменты памяти):

class Qsort {
    static int qsortCompare(MemorySegment elem1, MemorySegment elem2) {
        return Integer.compare(elem1.get(JAVA_INT, 0), elem2.get(JAVA_INT, 0));
    }
}

FunctionDescriptor comparDesc = FunctionDescriptor.of(JAVA_INT,
                                                      ADDRESS.withTargetLayout(JAVA_INT),
                                                      ADDRESS.withTargetLayout(JAVA_INT));
MethodHandle comparHandle = MethodHandles.lookup()
                                         .findStatic(Qsort.class, "qsortCompare",
                                                     comparDesc.toMethodType());

try (Arena arena = Arena.ofConfined()) {
    MemorySegment comparFunc = linker.upcallStub(comparHandle, comparDesc, arena);
    MemorySegment array = arena.allocateFrom(JAVA_INT, 0, 9, 3, 4, 6, 5, 1, 8, 2, 7);
    qsort.invokeExact(array, 10L, 4L, comparFunc);
    int[] sorted = array.toArray(JAVA_INT); // [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
}

Функции, возвращающие указатели

void *malloc(size_t size);

void free(void *ptr);

Сначала нам нужно создать дескрипторы методов вызова вниз для malloc и free, как показано ниже:

Linker linker = Linker.nativeLinker();

MethodHandle malloc = linker.downcallHandle(
    linker.defaultLookup().findOrThrow("malloc"),
    FunctionDescriptor.of(ADDRESS, JAVA_LONG)
);

MethodHandle free = linker.downcallHandle(
    linker.defaultLookup().findOrThrow("free"),
    FunctionDescriptor.ofVoid(ADDRESS)
);

MemorySegment segment = (MemorySegment)malloc.invokeExact(100);

MemorySegment allocateMemory(long byteSize, Arena arena) throws Throwable {
    MemorySegment segment = (MemorySegment) malloc.invokeExact(byteSize); // size = 0, scope = always alive
    return segment.reinterpret(byteSize, arena, s -> {
        try {
            free.invokeExact(s);
        } catch (Throwable e) {
            throw new RuntimeException(e);
        }
    });  // size = byteSize, scope = arena.scope()
}

try (Arena arena = Arena.ofConfined()) {
    MemorySegment segment = allocateMemory(100, arena);
} // 'free' called here

Функции с переменным числом аргументов

Следует отметить, что значения, передаваемые как аргументы с переменным числом, подвергаются стандартному преобразованию аргументов в C. Например, применяются следующие преобразования аргументов:

• _Bool -> unsigned int
• [signed] char -> [signed] int
• [signed] short -> [signed] int
• float -> double

Собственный компоновщик поддерживает только компоновку специализированной формы функции с переменным числом аргументов. Функцию с переменным числом аргументов в её специализированной форме можно скомпоновать с помощью описателя функции, описывающего специализированную форму. Кроме того, должен быть указан параметр компоновщика Linker.Option.firstVariadicArg(int), чтобы указать первый параметр с переменным числом в списке параметров. Соответствующая компоновка аргументов (если таковая имеется), а также все последующие компоновки аргументов в описателе специализированной функции называются компоновками аргументов с переменным числом.

Собственный компоновщик не выполняет автоматически стандартное преобразование аргументов. Однако, поскольку передача аргумента не преобразованного типа в качестве аргумента с переменным числом не поддерживается в C, собственный компоновщик отклонит попытку компоновки описателя специализированной функции с любыми компоновками значений аргументов с переменным числом, соответствующими типу C без преобразования. Поскольку размер типа C int зависит от платформы, то и набор отклоняемых компоновок будет зависеть от платформы. Например, в Linux/x64 компоновщик отклонит компоновки, соответствующие типам C _Bool, (unsigned) char, (unsigned) short и float (и другим). Метод canonicalLayouts() можно использовать для определения компоновки, соответствующей конкретному типу C.

Хорошо известной функцией с переменным числом аргументов является функция printf, определённая в стандартной библиотеке C:

int printf(const char *format, ...);

printf("%d plus %d equals %d", 2, 2, 4);

Linker linker = Linker.nativeLinker();
MethodHandle printf = linker.downcallHandle(
    linker.defaultLookup().findOrThrow("printf"),
        FunctionDescriptor.of(JAVA_INT, ADDRESS, JAVA_INT, JAVA_INT, JAVA_INT),
        Linker.Option.firstVariadicArg(1) // first int is variadic
);

 try (Arena arena = Arena.ofConfined()) {
     //prints "2 plus 2 equals 4"
     int res = (int)printf.invokeExact(arena.allocateFrom("%d plus %d equals %d"), 2, 2, 4);
 }

Соображения безопасности

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