Пакет java.lang.foreign

Предоставляет низкоуровневый доступ к памяти и функциям за пределами среды выполнения Java.

Доступ к внешней памяти

Основной абстракцией, используемой для доступа к внешней памяти, является MemorySegment^ПРЕВЬЮ, представляющая собой непрерывный участок памяти, расположенный как внутри, так и вне кучи Java. Обычно сегменты памяти выделяются с использованием Arena^ПРЕВЬЮ, которое управляет жизненным циклом областей памяти, поддерживающих выделенные им сегменты. Содержимое сегмента памяти описывается с помощью memory layout^ПРЕВЬЮ, предоставляющего базовые операции для запроса размеров, смещений и ограничений выравнивания. Макеты памяти также предоставляют альтернативный, более абстрактный способ доступа к сегментам памяти доступа к сегментам памяти с использованием обработчиков переменных^ПРЕВЬЮ, которые могут быть вычислены с помощью путей макета. Например, чтобы выделить внекучную область памяти, достаточно большой для хранения 10 значений примитивного типа int, и заполнить её значениями от 0 до 9, можно использовать следующий код:

try (Arena arena = Arena.ofConfined()) {
    MemorySegment segment = arena.allocate(10 * 4);
    for (int i = 0 ; i < 10 ; i++) {
        segment.setAtIndex(ValueLayout.JAVA_INT, i, i);
    }
}

Сегменты памяти обеспечивают строгие гарантии безопасности при доступе к памяти. Во-первых, при обращении к сегменту памяти координаты доступа проверяются (при доступе), чтобы убедиться, что доступ не происходит к любому адресу, который находится вне границ сегмента памяти, используемого операцией доступа. Мы называем эту гарантию пространственной безопасностью; другими словами, доступ к сегментам памяти проверяется на границу, точно так же, как проверка массивов, описанная в разделе 15.10.4 спецификации языка Java.

Кроме того, чтобы предотвратить доступ к области памяти после её освобождения (т. е. использование после освобождения), сегмент также проверяется (при доступе), чтобы убедиться, что область, из которой он был получен, не была закрыта. Мы называем эту гарантию временной безопасностью.

Вместе пространственная и временная безопасность гарантируют, что каждая операция доступа к памяти либо выполняется успешно — и обращается к допустимому месту в области памяти, поддерживающей сегмент памяти — либо терпит неудачу.

Доступ к внешним функциям

Например, чтобы вычислить длину строки с использованием стандартной функции C-библиотеки strlen на платформе Linux/x64, можно использовать следующий код:

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

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

Ограниченные методы

Привязка внешних данных и/или функций обычно небезопасна и, при неправильном выполнении, может привести к сбою JVM или к повреждению памяти при обращении к связанному элементу Java API. Например, неправильное изменение размера сегмента внешней памяти с помощью MemorySegment.reinterpret(long)^ПРЕВЬЮ может привести к сбою JVM или, что ещё хуже, к неявной порче памяти при попытке доступа к изменённому сегменту. По этим причинам крайне важно, чтобы код, вызывающий ограниченный метод, никогда не передавал аргументы, которые могут привести к неправильной привязке внешних данных и/или функций к API Java.

Учитывая потенциальную опасность ограниченных методов, среда выполнения Java выводит предупреждение в поток стандартной ошибки каждый раз, когда вызывается ограниченный метод. Такие предупреждения можно отключить, предоставив доступ к ограниченным методам выбранным модулям. Это можно сделать либо с помощью специфичных для реализации командных строк, либо программно, например, вызвав ModuleLayer.Controller.enableNativeAccess(java.lang.Module)^ПРЕВЬЮ.

Для каждого класса в этом пакете, если не указано иное, все аргументы методов ссылочного типа не должны быть null, и любой null аргумент вызовет NullPointerException. Этот факт не документируется отдельно для методов этого API.