Java 17: Foreign Functions & Memory API

Kate

Administrator
Команда форума
На дворе Java 17, а значит пора разобрать еще один интересный JEP, а именно JEP 412: Foreign Function & Memory API, который является переосмыслением двух предыдущих: Foreign-Memory Access API и Foreign Linker API.

История тянется еще с JDK 14 и по прежнему находится в инкубаторе, поэтому не забываем добавить -add-modules jdk.incubator.foreign для запуска.

46e03245b5b0281616b12f167033304f.jpg

Новый API дает возможность взаимодействовать с кодом и данными вне Java runtime. Теперь JVM может эффективно работать с нативными библиотеками и внешней памятью. Альтернатива JNI имеет улучшенную производительность и стабильность, а также возможность работать с разными видами памяти на разных платформах.

Function & Memory API предоставляют классы и интерфейсы для:

  • выделения внешней памяти MemorySegment, MemoryAddress, SegmentAllocator
  • управления памятью и доступа к ней MemoryLayout, MemoryHandles, MemoryAccess
  • управления жизненным циклом ресурсов ResourceScope
  • вызова внешних функций SymbolLookup, CLinker

Memory Segments​

Memory Segments это абстракции, которые представляют участки памяти. Они связаны как пространственными, так и временными ограничениями. Пространственные ограничения гарантируют что действия с сегментом не затронут память за его границами, а временные - что операции не смогут происходить после закрытия области ресурсов.

Сегменты могут быть нескольких типов:

  • Native segments - выделены с нуля в нативной памяти
  • Mapped segments - врапперы смапленой памяти
  • Array or buffer segments - врапперы существующих java массивов или буфферов
MemorySegment nativeSegment = MemorySegment
.allocateNative(100, ResourceScope.newImplicitScope());

MemorySegment mappedSegment = MemorySegment
.mapFile( Path.of("memory.file"),
0,
200,
READ_WRITE,
newImplicitScope() );

MemorySegment arraySegment = MemorySegment.ofArray(new int[100]);

MemorySegment bufferSegment = MemorySegment.ofByteBuffer(ByteBuffer.allocateDirect(100));

Memory Layouts​

MemoryLayout используются для декларативного описания сегментов памяти и дают возможность определить разбивку на элементы.

  • value layouts - описывают разметку со значениями базовых типов, таких как целочисленные и с плавающей точкой
  • padding layouts - используют в основном для выравнивания и представляют участки памяти, которые стоит игнорировать.
На примере ниже, sequence memory layout, который создает поочередно повторяющийся 32-битный layout 25 раз.

SequenceLayout intArrayLayout = MemoryLayout.sequenceLayout(25,
MemoryLayout.valueLayout(32, ByteOrder.nativeOrder()));

Resource scopes​

За жизненный цикл ресурсов отвечают resource scopes, которые бывают explicit (явные) и implicit (неявные):

  • explicit resource scopes, такие как, newConfinedScope() и newSharedScope() поддерживают детерминированное высвобождение ресурсов и могут быть явно закрыты методом close()
  • implicit resource scopes, например, newImplicitScope() не могут быть закрыты явно и вызов close() повлечет за собой эксепшн. Ресурсы освобождаются только после того как инстанс скоупа станет недоступен.
try (ResourceScope scope = ResourceScope.newConfinedScope()) {
var mappedSegment = MemorySegment.mapFile(Path.of("my.file"), 0, 100000, FileChannel.MapMode.READ_WRITE, scope);

var nativeSegment = MemorySegment.allocateNative(100, scope);
}

Скоупы ресурсов также можно разделить на: thread-confined, которые поддерживают строгое замыкание на поток и shared, с которыми могут взаимодействовать несколько потоков.

Segment allocators​

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

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

try (ResourceScope scope = ResourceScope.newConfinedScope()) {
SegmentAllocator allocator = SegmentAllocator.arenaAllocator(scope);
for (int i = 0 ; i < 100 ; i++) {
MemorySegment s = allocator
.allocateArray(C_INT, new int[] { 1, 2, 3 });
...
}
...
}

Looking up foreign functions​

Вызов внешних функций невозможен без загрузки нативных библиотек. В JNI эта цель достигалась при помощи System::loadLibrary и System::load методов. Библиотеки загруженные таким способом всегда связаны с класслоадером.

В FFM API механизм загрузки остался прежним. Но новый API позволяет находить адрес идентификаторов в загруженной библиотеке при помощи SymbolLookup, вызвать который можно двумя путями:

  • SymbolLookup::loaderLookup возвращает реализацию, которая ищет идентификаторы во всех библиотеках, загруженных текущим класслоадером
  • CLinker::systemLookup возвращает platform-dependent реализацию, которая ищет идентификаторы в стандартной C библиотеке
SymbolLookup::lookup(String) находит по имени метод в нативной библиотеке и возвращает MemoryAddress, который указывает на точку входа функции.

Для примера загрузим OpenGL библиотеку и найдем glGetString метод:

System.loadLibrary("GL");
SymbolLookup loaderLookup = SymbolLookup.loaderLookup();
MemoryAddress clangVersion = loaderLookup.lookup("glGetString").get();

Linking Java code to foreign functions​

Интерфейс CLinker описывает взаимодействие Java с нативным кодом. Основной фокус на отношениях Java и С, но концепт интерфейса подходит для поддержки других языков в будущем. Абстракция поддерживает downcalls и upcalls.

  • downcalls - вызывают нативные функции из Java кода как простой MethodHandle. Принимают в параметры MemoryAddress, полученный через lookup, MethodType, который описывает сигнатуру клиента и FunctionDescriptor по сути описывающий сигнатуру внешней функции.
  • upcalls - позволяют конвертировать существующий MethodHandle (который может ссылаться на обычный Java метод) в MemorySegment который может будет передан в нативную функцию как указатель.
Для примера вызовем функцию size_t strlen(const char *s); из С библиотеки:

MethodHandle strlen = CLinker.getInstance().downcallHandle(
CLinker.systemLookup().lookup("strlen").get(),
MethodType.methodType(long.class, MemoryAddress.class),
FunctionDescriptor.of(C_LONG, C_POINTER)
);

MemorySegment str = CLinker.toCString("Hello", newImplicitScope());
long len = strlen.invokeExact(str.address()); // 5

Summary​

Новый API для работы с нативными библиотеками это серьезных шаг в сторону безопасности таких операций. Много сценариев, которые требовали использование JNI, теперь могут решены при помощи FFM API.

В статье сделан краткий обзор ключевых моментов модуля jdk.incubator.foreign, основанный на JEP 412 и Javadocs 17-й версии. Думаю стоит присмотреться к новым возможностям.

Ждем выхода Foreign Function & Memory API из инкубатора.

 
Сверху