Интерфейс Linker

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