Интерфейс Linker

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

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

• Линкер позволяет коду Java связаться с внешними функциями через обработчики вызовов вниз; и
• Линкер позволяет внешним функциям вызывать обработчики методов Java, сгенерировав заглушки вызовов вверх.

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

size_t strlen(const char *s);

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

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

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

Скалярные типы C, такие как bool, int, моделируются как макеты значений^ПРЕВЬЮ подходящего носителя. Сопоставление между скалярным типом и соответствующим макетом зависит от ABI, реализованного нативным линкером. Например, тип C long сопоставляется со значением макета ValueLayout.JAVA_LONG^ПРЕВЬЮ на Linux/x64, но со значением макета ValueLayout.JAVA_INT^ПРЕВЬЮ на Windows/x64. Аналогично, тип C size_t сопоставляется со значением макета ValueLayout.JAVA_LONG^ПРЕВЬЮ на 64-битных платформах, но со значением макета ValueLayout.JAVA_INT^ПРЕВЬЮ на 32-битных платформах.

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

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

В следующей таблице приведены примеры моделирования типов C на Linux/x64:

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

Тип C	Макет	Тип Java
bool	ValueLayout.JAVA_BOOLEANПРЕВЬЮ	boolean
char	ValueLayout.JAVA_BYTEПРЕВЬЮ	byte
short	ValueLayout.JAVA_SHORTПРЕВЬЮ	short
int	ValueLayout.JAVA_INTПРЕВЬЮ	int
long	ValueLayout.JAVA_LONGПРЕВЬЮ	long
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(32), 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 поддерживается нативным линком NL если:

• L — это макет значения V и V.withoutName() равен^{равенПРЕВЬЮ} одному из следующих констант макетов:
  • ValueLayout.JAVA_BOOLEAN^ПРЕВЬЮ
  • ValueLayout.JAVA_BYTE^ПРЕВЬЮ
  • ValueLayout.JAVA_CHAR^ПРЕВЬЮ
  • ValueLayout.JAVA_SHORT^ПРЕВЬЮ
  • ValueLayout.JAVA_INT^ПРЕВЬЮ
  • ValueLayout.JAVA_LONG^ПРЕВЬЮ
  • ValueLayout.JAVA_FLOAT^ПРЕВЬЮ
  • ValueLayout.JAVA_DOUBLE^ПРЕВЬЮ
• L — это макет адреса A и A.withoutTargetLayout().withoutName() равен^{равенПРЕВЬЮ} ValueLayout.ADDRESS^ПРЕВЬЮ
• L — это макет последовательности S и выполняются все следующие условия:
  1. ограничение выравнивания S установлено в его естественное выравнивание, и
  2. S.elementLayout() — это макет, поддерживаемый NL.
• L — это макет группы G и выполняются все следующие условия:
  1. ограничение выравнивания G установлено в его естественное выравнивание;
  2. размер G кратен его ограничению выравнивания;
  3. каждый макет элемента в G.memberLayouts() — это либо макет заполнения, либо макет, поддерживаемый NL, и
  4. 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().find("qsort").orElseThrow(),
        FunctionDescriptor.ofVoid(ADDRESS, JAVA_LONG, JAVA_LONG, ADDRESS)
);

Чтобы вызвать полученный выше обработчик вызова qsort, нам нужно передать указатель на функцию в качестве последнего параметра. Для этого нужно создать указатель на функцию из существующего обработчика метода. Сначала напишем метод Java, который может сравнивать два элемента int, переданных как указатели (т.е. как сегменты памяти^ПРЕВЬЮ):

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.allocateArray(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().find("malloc").orElseThrow(),
    FunctionDescriptor.of(ADDRESS, JAVA_LONG)
);

MethodHandle free = linker.downcallHandle(
    linker.defaultLookup().find("free").orElseThrow(),
    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

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

1. С заключительным многоточием (...) в конце списка формальных параметров, например: void foo(int x, ...);
2. Со списком формальных параметров, называемым функцией без прототипа, например: void foo();

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

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

Собственный линковщик поддерживает только специализированную форму вариадной функции. Вариадную функцию в специализированной форме можно связать с помощью дескриптора функции, описывающего специализированную форму. Кроме того, необходимо указать параметр линковщика Linker.Option.firstVariadicArg(int)^{ПРОСМОТР} для указания первого вариадного параметра в списке параметров. Соответствующая структура аргументов (если она есть), а также все последующие структуры аргументов в дескрипторе специализированной функции называются структурами вариадных аргументов. Для функции без прототипа индекс, переданный Linker.Option.firstVariadicArg(int)^{ПРОСМОТР}, должен всегда быть 0.

Собственный линковщик отклонит попытку связать дескриптор специализированной функции с любыми структурами вариадных аргументов, соответствующими типу C, который подвергнется стандартному продвижению аргументов (как описано выше). Точно, какие структуры будут отклонены, зависит от платформы, но, например, на Linux/x64 будут отклонены структуры ValueLayout.JAVA_BOOLEAN^{ПРОСМОТР}, ValueLayout.JAVA_BYTE^{ПРОСМОТР}, ValueLayout.JAVA_CHAR^{ПРОСМОТР}, ValueLayout.JAVA_SHORT^{ПРОСМОТР} и ValueLayout.JAVA_FLOAT^{ПРОСМОТР}.

Известной вариадной функцией является функция 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().find("printf").orElseThrow(),
        FunctionDescriptor.of(JAVA_INT, ADDRESS, JAVA_INT, JAVA_INT, JAVA_INT),
        Linker.Option.firstVariadicArg(1) // first int is variadic
);

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

Вопросы безопасности

Когда вызов вверх передается во внешнюю функцию, может произойти сбой JVM, если внешние код приведёт указатель функции, связанный с вызовом вверх, к типу, несовместимому с типом вызова вверх, а затем попытается вызвать функцию с помощью полученного указателя функции. Кроме того, если обработчик метода, связанный с вызовом вверх, возвращает сегмент памяти^{ПРОСМОТР}, клиенты должны гарантировать, что этот адрес не может стать недействительным после завершения вызова вверх. Это может привести к неопределенному поведению и даже к сбою JVM, поскольку вызов вверх обычно выполняется в контексте вызова обработчика метода вниз.