JEP 424: Foreign Function & Memory API (Preview) | 外部函数和内存 API（预览）

原文

JEP 424: Foreign Function & Memory API (Preview)

摘要

介绍一个 API，通过该 API，Java 程序可以与 Java 运行时环境之外的代码和数据互操作。通过高效地调用外部函数（即 JVM 之外的代码）并安全地访问外部内存（即不由 JVM 管理的内存），该 API 使 Java 程序能够调用本地库并处理本地数据，同时避免了 JNI 的脆弱性和危险性。这是一个 预览 API。

历史

外部函数和内存（FFM）API 结合了之前两个 孵化 API：外部内存访问 API（JEPs 370、383 和 393）和外部链接器 API（JEP 389）。FFM API 通过 JEP 412 在 JDK 17 中孵化，并通过 JEP 419 在 JDK 18 中重新孵化。本 JEP 基于该 API 作为孵化 API 期间收到的反馈，对 FFM API 进行了改进。在 JDK 19 中，外部函数和内存 API 不再处于孵化阶段；相反，它是一个 预览 API。

目标

• 易用性 — 用一个更优秀、纯 Java 的开发模型取代 Java 本地接口（JNI）。

• 性能 — 提供与现有 API（如 JNI 和 sun.misc.Unsafe）相当甚至更好的性能。

• 通用性 — 提供在不同类型的外部内存（如本地内存、持久内存和托管堆内存）上操作的方法，并随着时间的推移，适应其他平台（如 32 位 x86）和用除 C 语言之外的语言（如 C++、Fortran）编写的外部函数。

• 安全性 — 允许程序对外部内存执行不安全操作，但默认情况下会警告用户这些操作。

非目标

不包括以下目标：

• 在此 API 之上重新实现 JNI，或以任何方式更改 JNI；
• 在此 API 之上重新实现遗留的 Java API，如 sun.misc.Unsafe；
• 提供从本机代码头文件自动生成 Java 代码的工具；
• 更改与本地库交互的 Java 应用程序的打包和部署方式（例如，通过多平台 JAR 文件）。

动机

Java 平台始终为希望超越 JVM 并与其他平台交互的库和应用程序开发人员提供了丰富的基础。Java API 能够方便且可靠地暴露非 Java 资源，无论是访问远程数据（JDBC）、调用 Web 服务（HTTP 客户端）、为远程客户端提供服务（NIO 通道），还是与本地进程通信（Unix 域套接字）。然而，Java 开发人员在访问一种重要的非 Java 资源时仍然面临重大障碍：即与 JVM 位于同一台机器上但位于 Java 运行时之外的代码和数据。

外部内存

存储在 Java 运行时之外的内存中的数据被称为 堆外 数据。（堆 是 Java 对象存储的地方——堆上 数据——也是垃圾收集器工作的地方。）对于流行的 Java 库（如 Tensorflow、Ignite、Lucene 和 Netty）的性能而言，访问堆外数据至关重要，这主要是因为它们可以避免与垃圾收集相关的成本和不可预测性。此外，通过例如 mmap 等方式将文件映射到内存中，还可以实现数据结构的序列化和反序列化。然而，Java 平台并没有为访问堆外数据提供令人满意的解决方案。

• ByteBuffer API 允许创建分配在堆外的 直接 字节缓冲区，但其最大大小为两吉字节，并且不会立即释放。这些以及其他限制源于 ByteBuffer API 的设计初衷不仅是为了访问堆外内存，还用于在字符集编码/解码和部分 I/O 操作等领域中进行生产者/消费者之间的批量数据交换。在该上下文中，无法满足多年来提交的许多堆外增强请求（例如，4496703、6558368、4837564 和 5029431）。

• sun.misc.Unsafe API 为堆上数据提供了内存访问操作，这些操作也适用于堆外数据。使用 Unsafe 是高效的，因为其内存访问操作被定义为 HotSpot JVM 内部函数，并由 JIT 编译器优化。然而，使用 Unsafe 是危险的，因为它允许访问任何内存位置。这意味着 Java 程序可以通过访问已释放的位置来崩溃 JVM；出于这一原因和其他原因，一直 强烈建议不要 使用 Unsafe。

• 使用 JNI 调用本地库以访问堆外数据是可能的，但性能开销很少使其适用：从 Java 到本地的转换比访问内存慢几个数量级，因为 JNI 方法调用无法享受许多常见的 JIT 优化，如内联。

总之，在访问堆外数据时，Java 开发人员面临一个困境：他们是应该选择安全但效率不高的路径（ByteBuffer），还是应该为了性能而放弃安全性（Unsafe）？他们实际上需要的是一个从底层开始设计时就考虑到安全性和 JIT 优化的、用于访问堆外数据（即外部内存）的受支持 API。

外部函数

自 Java 1.1 以来，JNI（Java Native Interface，Java 本地接口）一直支持调用本地代码（即外部函数），但出于多种原因，它存在不足。

• JNI 涉及多个繁琐的工件：Java API（native 方法）、从 Java API 派生的 C 头文件，以及调用目标本地库的 C 实现。Java 开发人员必须在多个工具链之间工作，以保持与平台相关的工件同步，这在本地库快速演变时尤其繁重。

• JNI 只能与通常用操作系统和 CPU 的调用约定编写的库（通常是 C 和 C++）进行互操作，这些库是为 JVM 构建的。native 方法不能用于调用使用不同约定的语言编写的函数。

• JNI 没有将 Java 类型系统与 C 类型系统相协调。Java 中的聚合数据用对象表示，而 C 中的聚合数据用结构体表示，因此任何传递给 native 方法的 Java 对象都必须由本地代码费力地解包。例如，考虑 Java 中的一个记录类 Person：将 Person 对象传递给 native 方法将要求本地代码使用 JNI 的 C API 从该对象中提取字段（如 firstName 和 lastName）。因此，Java 开发人员有时会将其数据展平为一个单独的对象（如字节数组或直接字节缓冲区），但更常见的是，由于通过 JNI 传递 Java 对象速度较慢，他们会使用 Unsafe API 分配堆外内存，并将其地址作为 long 类型传递给 native 方法——这会使 Java 代码变得非常不安全！

多年来，出现了许多框架来填补 JNI 留下的空白，包括 JNA、JNR 和 JavaCPP。虽然这些框架通常是对 JNI 的显著改进，但情况仍然不尽如人意，尤其是与提供一流本地互操作功能的语言相比。例如，Python 的 ctypes 包可以无需任何胶水代码，动态地包装本地库中的函数。其他语言，如 Rust，提供了从 C/C++ 头文件机械派生本地包装器的工具。

最终，Java 开发人员应该拥有一个受支持的 API，使他们能够直接使用任何被认为对特定任务有用的本地库，而无需 JNI 的繁琐和笨拙。一个优秀的抽象基础是 Java 7 中引入的 方法句柄，用于支持 JVM 上的快速动态语言。通过方法句柄暴露本地代码将极大地简化编写、构建和分发依赖于本地库的 Java 库的任务。此外，一个能够建模外部函数（即本地代码）和外部内存（即堆外数据）的 API 将为第三方本地互操作框架提供坚实的基础。

描述

外部函数与内存 API（FFM API）定义了类和接口，以便库和应用程序中的客户端代码可以

• 分配外部内存
  （MemorySegment、MemoryAddress 和 SegmentAllocator），
• 操作和访问结构化外部内存
  （MemoryLayout、VarHandle），
• 控制外部内存的分配和释放
  （MemorySession），以及
• 调用外部函数（Linker、FunctionDescriptor 和 SymbolLookup）。

FFM API 位于 java.base 模块的 java.lang.foreign 包中。

示例

作为使用 FFM API 的一个简短示例，以下是 Java 代码，它获取 C 库函数 radixsort 的方法句柄，然后使用它来排序最初位于 Java 数组中的四个字符串（省略了一些细节）。

由于 FFM API 是一个 预览 API，因此您必须在启用预览功能的情况下编译和运行代码，即使用 javac --release 19 --enable-preview ... 和 java --enable-preview ...。

// 1. 在 C 库路径上查找外部函数
Linker linker = Linker.nativeLinker();
SymbolLookup stdlib = linker.defaultLookup();
MethodHandle radixSort = linker.downcallHandle(
                             stdlib.lookup("radixsort"), ...);
// 2. 分配堆上内存以存储四个字符串
String[] javaStrings   = { "mouse", "cat", "dog", "car" };
// 3. 分配堆外内存以存储四个指针
SegmentAllocator allocator = SegmentAllocator.implicitAllocator();
MemorySegment offHeap  = allocator.allocateArray(ValueLayout.ADDRESS, javaStrings.length);
// 4. 将字符串从堆上复制到堆外
for (int i = 0; i < javaStrings.length; i++) {
    // 在堆外分配一个字符串，然后存储指向它的指针
    MemorySegment cString = allocator.allocateUtf8String(javaStrings[i]);
    offHeap.setAtIndex(ValueLayout.ADDRESS, i, cString);
}
// 5. 通过调用外部函数对堆外数据进行排序
radixSort.invoke(offHeap, javaStrings.length, MemoryAddress.NULL, '\0');
// 6. 将（重新排序后的）字符串从堆外复制到堆上
for (int i = 0; i < javaStrings.length; i++) {
    MemoryAddress cStringPtr = offHeap.getAtIndex(ValueLayout.ADDRESS, i);
    javaStrings[i] = cStringPtr.getUtf8String(0);
}
assert Arrays.equals(javaStrings, new String[] {"car", "cat", "dog", "mouse"});  // true

与任何使用 JNI 的解决方案相比，此代码更加清晰，因为原本隐藏在 native 方法调用背后的隐式转换和内存解引用现在直接在 Java 中表达。此外，还可以使用现代 Java 习语；例如，流可以允许多个线程并行地在堆上和堆外内存之间复制数据。

内存段

内存段 是一种抽象，用于模拟位于堆外或堆上的连续内存区域。内存段可以是

• 原生 段，从原生内存中从头开始分配（例如，通过 malloc），
• 映射 段，围绕映射的原生内存区域进行封装（例如，通过 mmap），或
• 数组 或 缓冲区 段，分别围绕与现有 Java 数组或字节缓冲区相关联的内存进行封装。

所有内存段都提供了严格的空间、时间和线程隔离保证，从而使内存解引用操作变得安全。例如，以下代码在堆外分配了 100 字节：

MemorySegment segment = MemorySegment.allocateNative(100,
                                                     MemorySession.openImplicit());

一个段的 空间边界 决定了与该段相关联的内存地址范围。上述代码中段的边界由一个 基地址 b（以 MemoryAddress 实例表示）和字节大小（100）定义，从而形成一个从 b 到 b+99（包含）的地址范围。

一个段的 时间边界 决定了段的生命周期，即段何时被释放。段的生命周期和线程隔离状态由 MemorySession 抽象表示，将在 下文 中讨论。上述代码中的内存会话是一个新的 隐式 会话，它确保当 MemorySegment 对象被垃圾收集器视为不可达时，与该段相关联的内存将被释放。隐式会话还确保内存段可以从多个线程访问。

换句话说，上述代码创建了一个其行为与通过 allocateDirect 工厂方法分配的 ByteBuffer 非常相似的段。FFM API 还支持确定性内存释放和其他线程隔离选项，将在 下文 中讨论。

解引用段

为了解引用内存段中的某些数据，我们需要考虑几个因素：

• 要解引用的字节数，
• 解引用发生时的地址对齐约束，
• 所述内存区域中字节的存储字节序，以及
• 解引用操作中要使用的 Java 类型（例如，int 与 float）。

所有这些特性都在 ValueLayout 抽象中捕获。例如，预定义的 JAVA_INT 值布局是四个字节宽，对齐在四个字节的边界上，使用原生平台的字节序（例如，在 Linux/x64 上为小端字节序），并与 Java 类型 int 相关联。

内存段具有简单的解引用方法来从内存段中读取和写入值。这些方法接受一个值布局，该布局唯一指定了解引用操作的属性。例如，我们可以使用以下代码在内存段的连续偏移量处写入 25 个 int 值：

MemorySegment segment = MemorySegment.allocateNative(100,
                                                     MemorySession.openImplicit());
for (int i = 0; i < 25; i++) {
    segment.setAtIndex(ValueLayout.JAVA_INT,
                       /* 索引 */ i,
                       /* 要写入的值 */ i);
}

内存布局和结构化访问

考虑以下 C 语言声明，它定义了一个 Point 结构体的数组，其中每个 Point 结构体有两个成员，即 Point.x 和 Point.y：

struct Point {
   int x;
   int y;
} pts[10];

使用上一节中展示的解引用方法，为了初始化这样的原生数组，我们需要编写以下代码：

MemorySegment segment = MemorySegment.allocateNative(2 * 4 * 10,
                                                     MemorySession.openImplicit());
for (int i = 0; i < 10; i++) {
    segment.setAtIndex(ValueLayout.JAVA_INT,
                       /* 索引 */ (i * 2),
                       /* 要写入的值 */ i); // x
    segment.setAtIndex(ValueLayout.JAVA_INT,
                       /* 索引 */ (i * 2) + 1,
                       /* 要写入的值 */ i); // y
}

为了减少对内存布局繁琐计算的需求（例如，上述示例中的 (i * 2) + 1），可以使用 MemoryLayout 以更声明性的方式来描述内存段的内容。例如，上述示例中所需的本机内存段布局可以按以下方式描述：

SequenceLayout ptsLayout
    = MemoryLayout.sequenceLayout(10,
                                  MemoryLayout.structLayout(
                                      ValueLayout.JAVA_INT.withName("x"),
                                      ValueLayout.JAVA_INT.withName("y")));

这创建了一个 序列内存布局，其中包含十个重复的 结构体布局，其元素分别是名为 x 和 y 的两个 JAVA_INT 布局。给定此布局，我们可以通过创建两个 内存访问变量句柄（特殊的 变量句柄，它们接受一个 MemorySegment 参数（要解引用的段），后跟一个或多个 long 坐标（解引用操作应发生的索引）），来避免在代码中计算偏移量：

VarHandle xHandle    // (MemorySegment, long) -> int
    = ptsLayout.varHandle(PathElement.sequenceElement(),
                          PathElement.groupElement("x"));
VarHandle yHandle    // (MemorySegment, long) -> int
    = ptsLayout.varHandle(PathElement.sequenceElement(),
                          PathElement.groupElement("y"));

MemorySegment segment = MemorySegment.allocateNative(ptsLayout,
                                                     MemorySession.openImplicit());
for (int i = 0; i < ptsLayout.elementCount().getAsLong(); i++) {
    xHandle.set(segment,
                /* 索引 */ (long) i,
                /* 要写入的值 */ i); // x
    yHandle.set(segment,
                /* 索引 */ (long) i,
                /* 要写入的值 */ i); // y
}

ptsLayout 对象通过创建一个 布局路径 来驱动内存访问变量句柄的创建，该路径用于从复杂的布局表达式中选择一个嵌套布局。由于所选的值布局与 Java 类型 int 相关联，因此生成的变量句柄 xHandle 和 yHandle 的类型也将是 int。此外，由于所选的值布局定义在序列布局内部，因此变量句柄会获得一个额外的类型为 long 的坐标，即要读取或写入的 Point 结构的索引。ptsLayout 对象还驱动本地内存段的分配，该分配基于从布局中派生的大小和对齐信息。由于使用不同的变量句柄来初始化 Point.x 和 Point.y 元素，因此在循环内部不再需要进行偏移量计算。

内存会话

上述所有示例都使用非确定性释放：与分配的内存段相关联的内存在内存段实例变得不可达后由垃圾收集器释放。我们说这样的段是 隐式释放 的。

在某些情况下，客户端可能希望控制内存释放的时机。例如，假设使用 MemorySegment::map 从文件中映射了一个大内存段。客户端可能希望在该段不再需要时立即释放（即取消映射）与该段相关联的内存，而不是等待垃圾收集器进行释放，因为等待可能会对应用程序的性能产生不利影响。

内存段通过 内存会话 支持确定性释放。内存会话模拟一个或多个内存段的生命周期。新创建的内存会话处于 活动 状态，这意味着可以安全地访问它所管理的所有段。根据客户端的请求，可以 关闭 内存会话，从而不再允许访问会话管理的段。MemorySession 类实现了 AutoCloseable 接口，因此内存会话可以与 try-with-resources 语句一起工作：

try (MemorySession session = MemorySession.openConfined()) {
    MemorySegment s1 = MemorySegment.map(Path.of("someFile"),
                                         0, 100000,
                                         MapMode.READ_WRITE, session);
    MemorySegment s2 = MemorySegment.allocateNative(100, session);
    ...
} // 在此处释放两个段

此代码创建了一个内存会话并使用它来创建两个段：一个映射段 (s1) 和一个本地段 (s2)。这两个段的生命周期与内存会话的生命周期相关联，因此在 try-with-resources 语句外部访问这些段（例如，使用内存访问变量句柄取消引用它们）将导致抛出运行时异常。

除了管理内存段的生命周期外，内存会话还控制哪些线程可以访问该段。一个 受限 的内存会话将访问限制在创建会话的线程上，而一个 共享 的内存会话则允许从任何线程进行访问。

无论是受限还是共享，内存会话都可以与一个 java.lang.ref.Cleaner 对象相关联，该对象在内存会话仍然处于活动状态但变得不可达时执行隐式释放，从而防止意外的内存泄漏。

段分配器

当客户端使用堆外内存时，内存分配往往会成为瓶颈。因此，FFM API 包含了 SegmentAllocator 抽象，它定义了用于分配和初始化内存段的实用操作。通过 SegmentAllocator 接口中的工厂获取段分配器。其中一个工厂返回隐式分配器，即一个由新隐式会话支持的本地段分配器。还提供了其他更优化的分配器。例如，以下代码创建了一个基于竞技场（arena）的分配器，并使用它来分配一个其内容由 Java int 数组初始化的段：

try (MemorySession session = MemorySession.openConfined()) {
    SegmentAllocator allocator = SegmentAllocator.newNativeArena(session);
    for (int i = 0 ; i < 100 ; i++) {
        MemorySegment s = allocator.allocateArray(JAVA_INT,
                                                  new int[] { 1, 2, 3, 4, 5 });
        ...
    }
    ...
} // 这里释放了所有分配的内存

此代码创建了一个受限的内存会话，然后创建了一个与该会话关联的无界竞技场分配器。此分配器分配一个内存段，并通过返回该预分配段的切片来响应分配请求。如果当前段没有足够的空间来满足分配请求，则会分配一个新的段。当与竞技场分配器关联的内存会话关闭时，分配器创建的所有段（即在 for 循环体内）所关联的所有内存都将被原子性地释放。此技术结合了由 MemorySession 抽象提供的确定性释放的优势，以及更灵活和可扩展的分配方案。在编写管理大量堆外段的代码时，它非常有用。

不安全的内存段

到目前为止，我们已经了解了内存段、内存地址和内存布局。只有内存段上才能进行解引用操作。由于内存段具有空间和时间界限，Java 运行时确保与给定段关联的内存被安全地解引用。然而，在某些情况下，客户端可能仅具有 MemoryAddress 实例，这在与本地代码交互时经常发生。为了解引用内存地址，客户端有两个选项：

• 首先，客户端可以使用 MemoryAddress 类中定义的解引用方法之一。这些方法是不安全的，因为内存地址没有空间或时间界限，因此 FFM API 无法确保被解引用的内存位置是有效的。

• 或者，客户端可以通过 MemorySegment::ofAddress 工厂将地址不安全地转换为段。此工厂为原始内存地址附加了新的空间和时间界限，以便允许解引用操作。该工厂返回的内存段是不安全的：原始内存地址可能与一个 10 字节长的内存区域相关联，但客户端可能会错误地高估该区域的大小，并创建一个 100 字节长的不安全内存段。稍后，这可能会导致尝试解引用与不安全段相关联的内存区域界限之外的内存，这可能会导致 JVM 崩溃，或者更糟糕的是，导致静默内存损坏。

这两个选项都是不安全的，因此是受限的，这意味着它们的使用会在运行时显示警告（请参阅下面的安全性部分以获取更多信息）。

对于下行调用（downcalls），downcallHandle 方法接收一个外部函数的地址——通常是通过库查找获得的 MemorySegment——并将该外部函数暴露为一个下行调用方法句柄。之后，Java 代码通过调用其 invoke（或 invokeExact）方法来调用这个下行调用方法句柄，从而执行外部函数。传递给方法句柄的 invoke 方法的任何参数都会传递给外部函数。

对于上行调用（upcalls），upcallStub 方法接收一个方法句柄——通常是指向 Java 方法的方法句柄，而不是下行调用方法句柄——并将其转换为 MemorySegment 实例。之后，当 Java 代码调用下行调用方法句柄时，该内存段将作为参数传递。实际上，这个内存段充当了函数指针的角色。（有关上行调用的更多信息，请参阅 下文。）

假设我们希望从 Java 调用标准 C 库中定义的 strlen 函数：

size_t strlen(const char *s);

客户端可以使用 本地链接器（通过 Linker::nativeLinker 访问）来链接 C 函数，这是一个符合 JVM 运行所在操作系统和 CPU 确定的 ABI（应用程序二进制接口）的 Linker 实现。可以如下获取暴露 strlen 的下行调用方法句柄（FunctionDescriptor 的细节稍后会描述）：

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

调用下行调用方法句柄将执行 strlen 函数，并将其结果提供给 Java。对于 strlen 的参数，我们使用一个辅助方法将 Java 字符串转换为堆外内存段（使用隐式分配器），然后按引用传递：

MemorySegment str = implicitAllocator().allocateUtf8String("Hello");
long len          = strlen.invoke(cString);  // 5

方法句柄非常适合用于暴露外部函数，因为 JVM 已经对方法句柄的调用进行了优化，直至原生代码级别。当方法句柄引用 class 文件中的方法时，调用方法句柄通常会导致目标方法被 JIT 编译；随后，JVM 通过将控制权转移到为目标方法生成的汇编代码来解释调用 MethodHandle::invokeExact 的 Java 字节码。因此，Java 中的传统方法句柄在幕后针对非 Java 代码；下行调用方法句柄是一个自然扩展，它允许开发人员明确针对非 Java 代码。方法句柄还具有称为 签名多态性 的特性，允许使用原始参数进行无装箱调用。总之，方法句柄使 Linker 能够以自然、高效和可扩展的方式暴露外部函数。

在 Java 中描述 C 类型

为了创建一个下行调用方法句柄，FFM（Foreign Function & Memory）API 要求客户端提供一个 FunctionDescriptor，该描述符描述了目标 C 函数的 C 参数类型和 C 返回类型。在 FFM API 中，C 类型通过 MemoryLayout 对象进行描述，例如使用 ValueLayout 来描述标量 C 类型，使用 GroupLayout 来描述 C 结构体类型。客户端通常拥有 MemoryLayout 对象来取消引用外部内存中的数据，并可以重用它们来获得 FunctionDescriptor。

FFM API 还使用 FunctionDescriptor 来推导下行调用方法句柄的类型。每个方法句柄都是强类型的，这意味着它对在运行时可以传递给其 invokeExact 方法的参数数量和类型有严格要求。例如，一个为接受一个 MemoryAddress 参数而创建的方法句柄不能通过 invokeExact(<MemoryAddress>, <MemoryAddress>) 来调用，即使 invokeExact 是一个可变参数方法。下行调用方法句柄的类型描述了客户端在调用下行调用方法句柄时必须使用的 Java 签名。它实际上是 C 函数的 Java 视图。

以一个例子来说明，假设一个下行调用方法句柄应该暴露一个接受 C int 并返回 C long 的 C 函数。在 Linux/x64 和 macOS/x64 上，C 类型 long 和 int 分别与预定义的布局 JAVA_LONG 和 JAVA_INT 相关联，因此所需的 FunctionDescriptor 可以通过 FunctionDescriptor.of(JAVA_LONG, JAVA_INT) 获得。然后，本地链接器将安排下行调用方法句柄的类型为 Java 签名 int 到 long。

如果目标 C 函数使用如 long、int 和 size_t 等标量类型，则客户端必须了解当前平台。这是因为标量 C 类型与布局常量的关联因平台而异。在 Windows/x64 上，C long 与 JAVA_INT 布局相关联，因此所需的 FunctionDescriptor 将是 FunctionDescriptor.of(JAVA_INT, JAVA_INT)，且下行调用方法句柄的类型将是 Java 签名 int 到 int。

再举一个例子，假设一个下行调用方法句柄应该暴露一个接受指针的 void C 函数。在所有平台上，C 指针类型都与预定义的布局 ADDRESS 相关联，因此所需的 FunctionDescriptor 可以通过 FunctionDescriptor.ofVoid(ADDRESS) 获得。然后，本地链接器将安排下行调用方法句柄的类型为 Java 签名 Addressable 到 void。Addressable 是 FFM API 中可以通过引用传递的实体的共同超类型，如 MemorySegment 和 MemoryAddress。

客户端可以在不了解当前平台的情况下使用 C 指针。客户端不需要知道当前平台上指针的大小，因为 ADDRESS 布局的大小是从当前平台推断出来的，也不需要区分如 int* 和 char** 这样的 C 指针类型。

最后，与 JNI 不同，本地链接器支持将结构化数据传递给外部函数。假设一个下行调用方法句柄应该暴露一个接受结构体的 void C 函数，该结构体由以下布局描述：

MemoryLayout SYSTEMTIME  = MemoryLayout.ofStruct(
  JAVA_SHORT.withName("wYear"),      JAVA_SHORT.withName("wMonth"),
  JAVA_SHORT.withName("wDayOfWeek"), JAVA_SHORT.withName("wDay"),
  JAVA_SHORT.withName("wHour"),      JAVA_SHORT.withName("wMinute"),
  JAVA_SHORT.withName("wSecond"),    JAVA_SHORT.withName("wMilliseconds")
);

所需的 FunctionDescriptor 可以通过 FunctionDescriptor.ofVoid(SYSTEMTIME) 获得。Linker 将安排下行调用方法句柄的类型为 Java 签名 MemorySegment 到 void。

与 C 结构体类型相关联的内存布局必须是一个复合布局，它定义了 C 结构体中所有字段的子布局，包括本地编译器可能插入的任何与平台相关的填充。

如果 C 函数返回按值传递的结构体（此处未显示），则必须在堆外分配一个新的内存段并将其返回给 Java 客户端。为实现这一点，downcallHandle 返回的方法句柄需要一个额外的 SegmentAllocator 参数，FFM API 使用它来分配一个内存段以保存 C 函数返回的结构体。

如前所述，虽然本地链接器实现的重点是提供 Java 和 C 库之间的互操作性，但 Linker 接口是语言中立的：它不了解 C 类型是如何定义的，因此客户端负责为 C 类型获取合适的布局定义。这一选择是有意为之的，因为 C 类型的布局定义（无论是简单的标量还是复杂的结构体）最终都是平台依赖的，因此可以由对给定目标平台有深入了解的工具机械生成。

为 C 函数包装 Java 参数

调用约定（Calling Convention）通过指定一种语言中的代码如何调用另一种语言中的函数、传递参数以及接收结果，来实现不同语言之间的互操作性。Linker API 在调用约定方面是中立的，但原生链接器实现原生支持多种调用约定，包括：Linux/x64、Linux/AArch64、macOS/x64 和 Windows/x64。由于它是用 Java 编写的，因此比 JNI 更易于维护和扩展，JNI 的调用约定被硬编码在 HotSpot 的 C++ 代码中。

考虑上面为 SYSTEMTIME 结构体/布局获取的 FunctionDescriptor 。根据 JVM 运行的操作系统和 CPU 的调用约定，当使用 MemorySegment 参数调用下行调用方法句柄时，原生链接器使用 FunctionDescriptor 来推断如何将该结构体的字段传递给 C 函数。对于一种调用约定，原生链接器实现可以安排分解传入的内存段，使用通用 CPU 寄存器传递前四个字段，并在 C 栈上传递剩余字段。对于不同的调用约定，原生链接器实现可以安排通过分配内存区域、批量复制传入内存段的内容到该区域，并将指向该内存区域的指针传递给 C 函数来间接传递结构体。这种最低级别的参数打包在幕后进行，无需客户端代码监督。

上行调用

有时，将 Java 代码作为函数指针传递给某些外部函数是很有用的。我们可以使用 Linker 对上行调用的支持来实现这一点。在本节中，我们将逐步构建一个更复杂的示例，展示 Linker 的全部功能，包括 Java/原生边界上的代码和数据的完整双向互操作性。

考虑在标准 C 库中定义的以下函数：

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

要从 Java 调用 qsort，我们首先需要创建一个下行调用方法句柄：

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

与之前一样，我们使用 JAVA_LONG 布局来映射 C 的 size_t 类型，并且对于第一个指针参数（数组指针）和最后一个参数（函数指针），我们都使用 ADDRESS 布局。

qsort 使用作为函数指针传递的自定义比较器函数 compar 对数组内容进行排序。因此，为了调用下行调用方法句柄，我们需要一个函数指针作为方法句柄的 invokeExact 方法的最后一个参数。Linker::upcallStub 通过使用现有的方法句柄来帮助我们创建函数指针，如下所示。

首先，我们在 Java 中编写一个 static 方法，该方法比较两个间接表示为 MemoryAddress 对象的 int 值：

class Qsort {
    static int qsortCompare(MemoryAddress addr1, MemoryAddress addr2) {
        return Integer.compare(addr1.get(JAVA_INT, 0), addr2.get(JAVA_INT, 0));
    }
}

其次，我们创建一个指向 Java 比较器方法的方法句柄：

MethodHandle comparHandle = MethodHandles.lookup()
                   .findStatic(Qsort.class, "qsortCompare",
                               MethodType.methodType(int.class,
                                                     MemoryAddress.class,
                                                     MemoryAddress.class));

第三，既然我们有了 Java 比较器的方法句柄，我们就可以使用 Linker::upcallStub 来创建一个函数指针。与下行调用一样，我们使用 FunctionDescriptor 来描述函数指针的签名：

MemorySegment comparFunc =
  linker.upcallStub(comparHandle,
                    /* 一个由 Java 方法实现的 C 函数的 Java 描述！ */
                    FunctionDescriptor.of(JAVA_INT, ADDRESS, ADDRESS),
                    MemorySession.openImplicit());
// 注意：上面的代码段末尾有一个多余的闭合括号，这里已移除

最后，我们得到了一个内存地址 comparFunc，它指向一个存根（stub），该存根可用于调用我们的 Java 比较器函数。现在，我们拥有了调用 qsort 下行调用句柄所需的一切：

MemorySegment array = implicitAllocator().allocateArray(
                                          ValueLayout.JAVA_INT,
                                          new int[] { 0, 9, 3, 4, 6, 5, 1, 8, 2, 7 });
qsort.invoke(array, 10L, ValueLayout.JAVA_INT.byteSize(), comparFunc);
int[] sorted = array.toIntArray(); // [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]

此代码创建了一个堆外数组，将 Java 数组的内容复制到其中，然后将该数组以及从原生链接器获得的比较器函数传递给 qsort 句柄。调用之后，堆外数组的内容将根据我们用 Java 编写的比较器函数进行排序。然后，我们从该段中提取一个新的 Java 数组，其中包含排序后的元素。

安全性

从根本上讲，Java 代码与本地代码之间的任何交互都可能破坏 Java 平台的完整性。链接到预编译库中的 C 函数本质上是不可靠的，因为 Java 运行时无法保证该函数的签名与 Java 代码的期望相匹配，甚至无法确保 C 库中的符号真的是一个函数。此外，即使链接了合适的函数，实际调用该函数也可能导致低级故障，如段错误，最终导致虚拟机崩溃。这种故障无法被 Java 运行时阻止，也无法被 Java 代码捕获。

使用 JNI 函数的本地代码尤其危险。此类代码可以通过使用如 getStaticField 和 callVirtualMethod 这样的函数，无需命令行标志（如 --add-opens）即可访问 JDK 内部。它还可以在 final 字段初始化后很长时间内更改其值。允许本地代码绕过应用于 Java 代码的检查会破坏 JDK 中的所有边界和假设。换句话说，JNI 本质上是不安全的。

JNI 无法被禁用，因此无法保证 Java 代码不会调用使用危险 JNI 函数的本地代码。这是对平台完整性的风险，对应用开发人员和最终用户来说几乎是不可见的，因为这些函数的使用通常有 99% 来自于应用程序和 JDK 之间的第三方、第四方和第五方库。

FFM API 的大部分设计上是安全的。过去需要使用 JNI 和本地代码的场景，现在可以通过调用 FFM API 中的方法来实现，而不会破坏 Java 平台。例如，JNI 的一个主要用途是灵活的内存分配，现在可以使用一个简单的 MemorySegment::allocateNative 方法来实现，该方法不涉及任何本地代码，并且总是返回由 Java 运行时管理的内存。一般来说，使用 FFM API 的 Java 代码不会导致 JVM 崩溃。

然而，FFM API 的一部分本质上是不安全的。在与 Linker 交互时，Java 代码可以通过指定与底层外部函数不兼容的参数类型来请求下行调用方法句柄。在 Java 中调用下行调用方法句柄将导致与在 JNI 中调用 native 方法时相同的结果——VM 崩溃或未定义行为。FFM API 还可以生成不安全的段，即其空间和时间界限由用户提供且无法由 Java 运行时验证的内存段（请参阅 MemorySegment::ofAddress）。

FFM API 中的不安全方法并不具有与 JNI 函数相同的风险；例如，它们不能更改 Java 对象中 final 字段的值。另一方面，FFM API 中的不安全方法很容易从 Java 代码中调用。因此，FFM API 中不安全方法的使用是 受限的：允许其使用，但默认情况下，每次使用都会在运行时发出警告。要使模块 M 中的代码能够无警告地使用不安全方法，请在 java 命令行上指定 --enable-native-access=M 选项。（使用逗号分隔的列表指定多个模块；指定 ALL-UNNAMED 以允许类路径上所有代码无警告地使用。）当此选项存在时，从指定模块列表外部的任何不安全方法的使用都将导致抛出 IllegalCallerException，而不是发出警告。在未来的版本中，可能需要此选项才能使用不安全方法。

我们并不打算在这里限制 JNI 的任何方面。在 Java 中调用 native 方法以及本地代码调用不安全的 JNI 函数仍然是可能的。然而，在未来的版本中，我们可能会以某种方式限制 JNI。例如，不安全的 JNI 函数，如 newDirectByteBuffer，可能会像 FFM API 中的不安全方法一样被默认禁用。更广泛地说，JNI 机制是如此不可挽回地危险，我们希望库能够优先选择纯 Java 的 FFM API 来进行安全和不安全的操作，以便将来我们可以默认禁用所有 JNI。这与 Java 的更广泛路线图相一致，即让平台开箱即用即安全，要求最终用户选择参与不安全的活动，如破坏强封装或链接到未知代码。

我们不打算在这里以任何方式更改 sun.misc.Unsafe。FFM API 对堆外内存的支持是 sun.misc.Unsafe 中围绕 malloc 和 free 的包装器（即 allocateMemory、setMemory、copyMemory 和 freeMemory）的一个绝佳替代方案。我们希望需要堆外存储的库和应用程序采用 FFM API，以便将来我们可以弃用并最终移除这些 sun.misc.Unsafe 方法。

备选方案

继续使用 java.nio.ByteBuffer、sun.misc.Unsafe、JNI 以及其他第三方框架。

风险和假设

创建一个既安全又高效的访问外部内存的 API 是一项艰巨的任务。由于前面章节中描述的空间和时间检查需要在每次访问时执行，因此 JIT 编译器必须能够优化这些检查，例如将它们提升到热循环之外，这一点至关重要。JIT 实现可能需要一些工作来确保 API 的使用与现有 API（如 ByteBuffer 和 Unsafe）的使用一样高效且可优化。此外，JIT 实现还需要确保从 API 获取的本地方法句柄的使用至少与现有 JNI 本地方法的使用一样高效且可优化。

依赖项

• Foreign Function & Memory API 可用于以更通用和高效的方式访问非易失性内存，这已通过 JEP 352（非易失性映射字节缓冲区） 实现。

• 这里描述的工作可能会为后续工作提供工具支持，即 jextract，该工具可以根据给定本地库的头文件自动生成与该库互操作所需的本地方法句柄。这将进一步减少从 Java 使用本地库的开销。