JEP 434：外部函数和内存 API（第二次预览）
总结
引入一个 API，通过它 Java 程序可以与 Java 运行时之外的代码和数据进行互操作。通过高效调用外部函数（即 JVM 之外的代码），以及安全地访问外部内存（即不受 JVM 管理的内存），该 API 使 Java 程序能够调用本地库并处理本地数据，而无需担心 JNI 的脆弱性和危险性。这是一个 预览 API。
历史
MemorySegment和MemoryAddress抽象被统一（内存地址现在由长度为零的内存段来表示）；- 密封的
MemoryLayout层次结构得到增强，以便在switch表达式和语句中更方便地与模式匹配一起使用（JEP 433），并且 MemorySession已被拆分为Arena和SegmentScope，以便于跨维护边界共享段。
目标
-
易用性 — 使用更优越的纯 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 的限制并与其它平台进行交互。无论是在访问远程数据（JDBC）、调用 Web 服务（HTTP 客户端）、服务远程客户端（NIO 通道）还是与本地进程通信（Unix 域套接字）时，Java API 都能方便且可靠地暴露非 Java 资源。然而，Java 开发者在访问一种重要的非 Java 资源时仍然面临显著的障碍：即与 JVM 处于同一台机器上但位于 Java 运行环境之外的代码和数据。
外部内存
使用 new 关键字创建的对象存储在 JVM 的 堆 中，当这些对象不再被需要时，它们会受到垃圾回收机制的管理。然而，对于像 Tensorflow、Ignite、Lucene 和 Netty 这样的对性能要求极高的库来说，垃圾回收所带来的开销和不可预测性是不可接受的。它们需要将数据存储在堆外的 off-heap 内存中，并自行分配和释放内存。通过访问堆外内存，还可以利用诸如 mmap 等方式，直接将文件映射到内存中以实现数据的序列化和反序列化。
Java 平台历史上提供了两个用于访问堆外内存的 API：
-
ByteBufferAPI 提供了直接字节缓冲区，这些缓冲区是通过堆外固定大小的内存区域支持的 Java 对象。然而，一个区域的最大大小被限制为 2 GB，并且用于读写内存的方法非常基础且容易出错，提供的功能几乎仅限于对原始值的索引访问。更严重的是，支持直接字节缓冲区的内存在缓冲区对象被垃圾回收之前不会被释放，而开发者无法控制垃圾回收。由于缺乏对及时释放的支持，使得ByteBufferAPI 不适合用于 Java 中的系统编程。 -
sun.misc.UnsafeAPI 提供了对堆内存的底层访问，同时也适用于堆外内存。使用Unsafe很快（因为其内存访问操作会被 JVM 内联优化），允许超大的堆外区域（理论上可达 16 EB），并提供了对释放操作的细粒度控制（因为可以随时调用Unsafe::freeMemory）。然而，这种编程模型较为薄弱，因为它赋予了开发者过多的控制权。在一个长时间运行的服务器应用程序中，库会随着时间推移分配并与多个堆外内存区域交互；一个区域中的数据可能指向另一个区域中的数据，区域必须按照正确的顺序释放，否则悬空指针会导致释放后使用（use-after-free）的错误。由于缺乏对安全释放的支持，UnsafeAPI 也不适合用于 Java 的系统编程。（同样的批评也适用于 JDK 外部的那些通过包装调用
malloc和free的原生代码来提供细粒度分配和释放的 API。）
总之，成熟的客户端应该拥有能够分配、操作和共享堆外内存的 API，且要像堆内内存一样流畅和安全。这样的 API 应该在可预测的释放需求与防止导致 JVM 崩溃或更糟糕的静默内存损坏的过早释放需求之间取得平衡。
外部函数
自 Java 1.1 起，JNI 就支持调用原生代码（即外部函数），但出于许多原因，它并不完善。
-
JNI 包含多个繁琐的构件：一个 Java API（
native方法）、从 Java API 派生的 C 头文件，以及调用目标原生库的 C 实现。Java 开发人员必须跨多个工具链工作，以保持与平台相关的构件同步，当原生库快速演进时，这尤其繁重。 -
JNI 只能与使用 JVM 构建所针对的操作系统和 CPU 调用约定的语言（通常是 C 和 C++）编写的库进行互操作。
native方法不能用于调用使用不同约定编写语言中的函数。 -
JNI 并未协调 Java 类型系统与 C 类型系统。Java 中的聚合数据使用对象表示，而 C 中的聚合数据使用结构体表示，因此传递给
native方法的任何 Java 对象都必须由原生代码费力地解包。例如，考虑 Java 中的一个记录类Person：将一个Person对象传递给native方法将需要原生代码使用 JNI 的 C API 从该对象中提取字段（例如，firstName和lastName）。结果是，Java 开发人员有时会将其数据展平为单个对象（例如，字节数组或直接字节缓冲区），但更多时候，由于通过 JNI 传递 Java 对象速度较慢，他们会使用UnsafeAPI 分配堆外内存，并将其地址作为long类型传递给native方法 —— 这使得 Java 代码变得极其不安全！
最终，Java 开发者应该拥有一个受支持的 API，使他们能够直接使用任何被认为对特定任务有用的原生库，而无需 JNI 的繁琐粘连和笨拙。一个极佳的抽象构建基础是 method handles（方法句柄），它在 Java 7 中被引入以支持 JVM 上的快速动态语言。通过方法句柄暴露原生代码将极大简化编写、构建和分发依赖于原生库的 Java 库的任务。此外，一个能够建模外部函数（即，原生代码）和外部内存（即，堆外数据）的 API 将为第三方原生互操作框架提供坚实的基础。
描述
外部函数和内存 API（FFM API）定义了类和接口，以便库和应用程序中的客户端代码可以使用。
- 分配外部内存
(MemorySegment和SegmentAllocator)， - 操作和访问结构化外部内存
(MemoryLayout和VarHandle)， - 控制外部内存的分配与释放
(SegmentScope和Arena)， - 调用外部函数 (
Linker,FunctionDescriptor, 和SymbolLookup)。
FFM API 位于 java.base 模块的 java.lang.foreign 包中。
示例
作为使用 FFM API 的一个简单示例，以下是获取 C 库函数 radixsort 的方法句柄的 Java 代码，然后使用它对从 Java 数组开始的四个字符串进行排序（省略了一些细节）。
由于 FFM API 是一个预览版 API，因此您必须在启用预览功能的情况下编译和运行代码，即 javac --release 20 --enable-preview ... 和 java --enable-preview ...。
// 1. Find foreign function on the C library path
Linker linker = Linker.nativeLinker();
SymbolLookup stdlib = linker.defaultLookup();
MethodHandle radixsort = linker.downcallHandle(stdlib.find("radixsort"), ...);
// 2. Allocate on-heap memory to store four strings
String[] javaStrings = { "mouse", "cat", "dog", "car" };
// 3. Use try-with-resources to manage the lifetime of off-heap memory
try (Arena offHeap = Arena.openConfined()) {
// 4. Allocate a region of off-heap memory to store four pointers
MemorySegment pointers = offHeap.allocateArray(ValueLayout.ADDRESS, javaStrings.length);
// 5. Copy the strings from on-heap to off-heap
for (int i = 0; i < javaStrings.length; i++) {
MemorySegment cString = offHeap.allocateUtf8String(javaStrings[i]);
pointers.setAtIndex(ValueLayout.ADDRESS, i, cString);
}
// 6. Sort the off-heap data by calling the foreign function
radixsort.invoke(pointers, javaStrings.length, MemorySegment.NULL, '\0');
// 7. Copy the (reordered) strings from off-heap to on-heap
for (int i = 0; i < javaStrings.length; i++) {
MemorySegment cString = pointers.getAtIndex(ValueLayout.ADDRESS, i);
javaStrings[i] = cString.getUtf8String(0);
}
} // 8. All off-heap memory is deallocated here
assert Arrays.equals(javaStrings, new String[] {"car", "cat", "dog", "mouse"}); // true
这段代码比任何使用 JNI 的解决方案都要清晰得多，因为隐式转换和内存访问原本隐藏在 native 方法调用的背后，而现在可以直接用 Java 表达。还可以使用现代的 Java 习惯用法；例如，流（streams）可以允许多个线程并行地在堆内和堆外内存之间复制数据。
内存段和作用域
一个内存段 是由一块连续的内存区域支持的抽象，该内存区域可以位于堆外或堆内。一个内存段可以是
- 一个原生段，从无到有分配自堆外内存（如同通过
malloc进行分配）， - 一个映射段，包裹着一块映射的堆外内存区域（如同通过
mmap进行分配），或者 - 一个数组或缓冲区段，分别包裹着与现有 Java 数组或字节缓冲区相关联的一块堆内内存区域。
所有内存段都提供了空间、时间和线程限制的保证，这些保证使内存访问操作变得安全。
段的空间边界决定了与该段关联的内存地址范围。例如，下面的代码分配了一个本地段，其边界由基地址 b 和大小（以字节为单位，100）定义，从而产生的地址范围从 b 到 b + 99（含）。
MemorySegment data = MemorySegment.allocateNative(100, SegmentScope.global());
一个段的时间界限决定了它的生命周期，即支持该段的内存区域被释放之前的这段时间。时间界限在分配段时由段作用域指定。只有当内存段的作用域处于活动状态时，才能访问该内存段，这表明支持该段的内存区域仍然已分配。尝试访问作用域不活动的内存段将因异常而失败。
最简单的段作用域是全局作用域，它提供了一个无限制的生命周期：它始终存在。使用全局作用域分配的段（如上面的代码所示）始终可访问，并且支持该段的内存区域永远不会被释放。
然而，大多数程序需要在运行时释放堆外内存，因此需要具有有限生命周期的内存段。
一个 自动 作用域提供了一个有限的生命周期：它会一直存在，直到 JVM 的垃圾回收器检测到该内存段不可达为止，此时支持该段的内存区域会被释放。例如，以下方法分配了一个具有自动作用域的段：
void processData() {
MemorySegment data = MemorySegment.allocateNative(100, SegmentScope.auto());
... use the 'data' variable ...
... use the 'data' variable some more ...
} // The region of memory backing the 'data' segment will be deallocated here (or later)
只要 data 变量没有泄露出方法，该段最终将被检测为不可达，并且其支持的区域将被释放。
自动作用域的生命周期虽然是有界的，但并不总是足够非确定性的。例如，一个从文件映射内存段的 API 应该允许客户端确定性地释放支持该段的内存区域，因为等待垃圾回收器可能对性能产生不利影响。
arena 作用域提供了一个有限且确定的生命周期：它从客户端打开 arena 的那一刻开始，到客户端关闭该 arena 时结束。每个 arena 都有自己的作用域；使用相同 arena 作用域分配的多个段享有相同的有限生命周期，并且可以安全地包含相互引用。例如，以下代码打开一个 arena，并使用该 arena 的作用域来指定两个段的生命周期：
try (Arena arena = Arena.openConfined()) {
MemorySegment segment1 = arena.allocate(100);
MemorySegment segment2 = arena.allocate(200);
// segments can safely reference each other
}
MemorySegment input = null, output = null;
try (Arena processing = Arena.openConfined()) {
input = MemorySegment.allocateNative(100, processing.scope());
... set up data in 'input' ...
output = MemorySegment.allocateNative(100, processing.scope());
... process data from 'input' to 'output' ...
... calculate the ultimate result from 'output' and store it elsewhere ...
} // the regions of memory backing the segments are deallocated here
...
input.get(ValueLayout.JAVA_BYTE, 0); // throws IllegalStateException (also for 'output')
当通过 try-with-resources 操作关闭竞技场时，竞技场作用域将不再存活，段会被失效，并且支持这些段的内存区域会被自动释放。
竞技场（Arenas）提供了一种强大的时间安全性保证：在竞技场关闭后，无法再访问以其作用域分配的内存段，因为此时该竞技场的作用域已不再有效。这种保证的成本取决于可以访问该内存段的线程数量。如果一个竞技场由同一个线程打开和关闭，并且使用该竞技场作用域分配的所有内存段仅由该线程访问，那么确保正确性非常简单。然而，如果使用竞技场作用域分配的内存段被多个线程访问，确保正确性就会变得复杂；例如，一个使用竞技场作用域分配的内存段可能正被一个线程访问，而另一个线程试图关闭该竞技场。为了在保证时间安全性的同时不让单线程客户端付出过多代价，竞技场分为两种类型：受限（confined） 和 共享（shared）。
-
受限竞技场（
Arena::openConfined）支持强大的线程隔离保证。受限竞技场有一个拥有者线程，通常是打开它的线程。在受限竞技场中分配的内存段（即，使用受限竞技场的作用域）只能由拥有者线程访问。任何尝试从非拥有者线程关闭受限竞技场的操作都会因异常而失败。 -
共享竞技场（
Arena::openShared）没有拥有者线程。在共享竞技场中分配的内存段可以被多个线程访问。此外，共享竞技场可以被任何线程关闭，并且即使在竞争条件下，关闭操作也保证是安全和原子性的。
总之，段作用域控制哪些线程可以访问内存段，以及何时可以访问。具有全局作用域或自动作用域的内存段可以被任何线程访问。相反，arena 作用域限制对特定线程的访问，以提供强大的时间安全性和可预测的性能模型。
解引用段
要对某个内存段中的数据进行解引用，我们需要考虑几个因素：
- 要解引用的字节数，
- 发生解引用的地址的对齐约束，
- 字节在内存段中存储的字节序，以及
- 解引用操作中使用的 Java 类型（例如，
int与float）。
所有这些特性都包含在 ValueLayout 抽象中。例如，预定义的 JAVA_INT 值布局宽度为四个字节，在四字节边界上对齐，使用本地平台的字节序（例如，在 Linux/x64 上为小端序），并且与 Java 类型 int 相关联。
内存段具有简单的解引用方法，用于从内存段读取和写入值。这些方法接受一个值布局，该布局唯一地指定了解引用操作的属性。例如，我们可以使用以下代码在内存段的连续偏移位置写入 25 个 int 值：
MemorySegment segment = MemorySegment.allocateNative(100, // size
ValueLayout.JAVA_INT.byteAlignment, // alignment
SegmentScope.auto());
for (int i = 0; i < 25; i++) {
segment.setAtIndex(ValueLayout.JAVA_INT,
/* index */ i,
/* value to write */ i);
}
内存布局与结构化访问
考虑以下 C 语言声明，它定义了一个 Point 结构体数组，其中每个 Point 结构体有两个成员，分别是 Point.x 和 Point.y：
struct Point {
int x;
int y;
} pts[10];
使用上一节中展示的解引用方法，要初始化这样的原生数组，我们必须编写以下代码（下面假设 sizeof(int) == 4）：
MemorySegment segment = MemorySegment.allocateNative(2 * ValueLayout.JAVA_INT.byteSize() * 10, // size
ValueLayout.JAVA_INT.byteAlignment, // alignment
SegmentScope.auto());
for (int i = 0; i < 10; i++) {
segment.setAtIndex(ValueLayout.JAVA_INT,
/* index */ (i * 2),
/* value to write */ i); // x
segment.setAtIndex(ValueLayout.JAVA_INT,
/* index */ (i * 2) + 1,
/* value to write */ i); // y
}
为了减少对繁琐的内存布局计算的需求（例如，上面示例中的 (i * 2) + 1），可以使用 MemoryLayout 以更声明式的方式描述内存段的内容。例如，上述示例中本地内存段的所需布局可以用以下方式描述：
SequenceLayout ptsLayout
= MemoryLayout.sequenceLayout(10,
MemoryLayout.structLayout(
ValueLayout.JAVA_INT.withName("x"),
ValueLayout.JAVA_INT.withName("y")));
这将创建一个 sequence memory layout，其中包含十个重复的 struct layout，其元素分别是名为 x 和 y 的两个 JAVA_INT 布局。有了这个布局，我们可以通过创建两个 memory-access var handles 来避免在代码中计算偏移量，这些特殊的 var handles 接受一个 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, SegmentScope.auto());
for (int i = 0; i < ptsLayout.elementCount(); i++) {
xHandle.set(segment,
/* index */ (long) i,
/* value to write */ i); // x
yHandle.set(segment,
/* index */ (long) i,
/* value to write */ i); // y
}
ptsLayout 对象通过创建一个布局路径来驱动内存访问变量句柄的创建，该路径用于从复杂的布局表达式中选择嵌套布局。由于所选的值布局与 Java 类型 int 相关联，因此生成的变量句柄 xHandle 和 yHandle 的类型也将是 int。此外，由于所选的值布局定义在序列布局内，变量句柄会获得一个额外的 long 类型坐标，即要读取或写入的 Point 结构体的索引。ptsLayout 对象还驱动了本地内存段的分配，这是基于从布局中获取的大小和对齐信息。由于使用了不同的变量句柄来初始化 Point.x 和 Point.y 元素，循环内不再需要进行偏移量计算。
段分配器
当客户端使用堆外内存时，内存分配往往是一个瓶颈。因此，FFM API 包含了一个 SegmentAllocator 抽象，用于定义分配和初始化内存段的操作。为了方便起见，Arena 类实现了 SegmentAllocator 接口，这样就可以使用 Arena 来分配本地内存段。换句话说，Arena 是一个灵活分配和及时释放堆外内存的“一站式解决方案”：
try (Arena offHeap = Arena.openConfined()) {
MemorySegment nativeArray = offHeap.allocateArray(ValueLayout.JAVA_INT, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
MemorySegment nativeString = offHeap.allocateUtf8String("Hello!");
MemorySegment upcallStub = linker.upcallStub(handle, desc, offHeap.scope());
...
} // memory released here
段分配器也可以通过 SegmentAllocator 接口中的工厂方法获取。其中一个工厂方法返回一个本地分配器，即一种为与给定段作用域相关联的本地段分配内存的分配器。此外还提供了其他一些更优化的分配器。例如，以下代码创建了一个切片分配器，并使用它分配一个内容从 Java int 数组初始化的段：
try (Arena arena = Arena.openConfined()) {
SegmentAllocator allocator = SegmentAllocator.slicingAllocator(arena.allocate(1024));
for (int i = 0 ; i < 10 ; i++) {
MemorySegment s = allocator.allocateArray(JAVA_INT, new int[] { 1, 2, 3, 4, 5 });
...
}
...
} // all memory allocated is released here
此代码创建了一个大小为 1024 字节的原生段。然后使用该段创建一个切片分配器，该分配器通过返回预先分配的段的切片来响应分配请求。如果当前段没有足够的空间来容纳分配请求，则会抛出异常。当竞技场关闭时，与分配器创建的段（即在 for 循环主体中）相关的所有内存都会被原子性地释放。这种技术结合了由 Arena 抽象提供的确定性释放的优势以及更灵活和可扩展的分配方案。在编写管理大量堆外段的代码时，这种技术非常有用。
查找外部函数
任何对外部函数支持的第一个要素都是在已加载的本地库中查找给定符号地址的机制。这种能力由 SymbolLookup 对象表示，对于将 Java 代码链接到外部函数至关重要（参见下文）。FFM API 支持三种不同类型的符号查找对象：
-
SymbolLookup::libraryLookup(String, SegmentScope)创建一个库查找，它定位用户指定的原生库中的所有符号。创建查找对象会导致库被加载（例如，使用dlopen()），并关联到一个SegmentScope对象。当提供的段作用域不再活跃时，库会被卸载（例如，使用dlclose()）。 -
SymbolLookup::loaderLookup()创建一个加载器查找，它定位当前类加载器中通过System::loadLibrary和System::load方法加载的所有原生库中的所有符号。 -
Linker::defaultLookup()创建一个默认查找，它定位与Linker实例相关的操作系统和处理器组合上常用库中的所有符号。
给定一个符号查找，客户端可以使用 SymbolLookup::find(String) 方法找到一个外部函数。如果命名的函数存在于符号查找可见的符号之中，那么该方法会返回一个零长度的内存段（见下文），其基地址指向函数的入口点。例如，以下代码使用加载器查找来加载 OpenGL 库并找到其 glGetString 函数的地址：
try (Arena arena = Arena.openConfined()) {
SymbolLookup opengl = SymbolLookup.libraryLookup("libGL.so", arena);
MemorySegment glVersion = opengl.find("glGetString").get();
...
} // libGL.so unloaded here
SymbolLookup::libraryLookup(String, SegmentScope) 与 JNI 的库加载机制（即 System::loadLibrary）在一个重要方面有所不同。设计为与 JNI 协作的原生库可以使用 JNI 函数来执行 Java 操作，例如对象分配或方法访问，这可能会触发 类加载。因此，这类与 JNI 相关的库在被 JVM 加载时必须与某个类加载器关联。接着，为了维护 类加载器完整性，同一个与 JNI 相关的库不能从不同类加载器定义的类中加载。相比之下，FFM API 并未提供让原生代码访问 Java 环境的函数，也不假定原生库是为与 FFM API 协作而设计的。通过 SymbolLookup::libraryLookup(String, SegmentScope) 加载的原生库并不知道它们是由运行在 JVM 中的代码访问的，也不会尝试执行任何 Java 操作。因此，它们不绑定到特定的类加载器，并且可以按需由不同加载器中的 FFM API 客户端多次（重新）加载。
将 Java 代码链接到外部函数
Linker 接口是 Java 代码与外部代码互操作的核心。虽然在本文档中我们经常提到 Java 和 C 库之间的互操作，但此接口中的概念足够通用，能够支持未来其他非 Java 语言。Linker 接口支持 downcalls（从 Java 代码调用到原生代码）和 upcalls（从原生代码回调到 Java 代码）。
interface Linker {
MethodHandle downcallHandle(Addressable func,
FunctionDescriptor function);
MemorySegment upcallStub(MethodHandle target,
FunctionDescriptor function,
SegmentScope scope);
}
对于向下调用，downcallHandle 方法接收一个外部函数的地址（通常是从库查找中获得的 MemorySegment），并将该外部函数暴露为一个 向下调用方法句柄。随后，Java 代码通过调用其 invoke（或 invokeExact）方法来调用这个向下调用方法句柄，外部函数便会运行。传递给方法句柄 invoke 方法的任何参数都会被传递给外部函数。
对于上行调用，upcallStub 方法接受一个方法句柄 —— 通常是指向 Java 方法的句柄，而不是下行调用方法句柄 —— 并将其转换为 MemorySegment 实例。随后，在 Java 代码调用下行调用方法句柄时，该内存段作为参数传递。实际上，内存段充当了函数指针的作用。（有关上行调用的更多信息，请参见下文。）
假设我们要从 Java 向标准 C 库中定义的 strlen 函数进行下层调用：
size_t strlen(const char *s);
客户端可以使用 native linker（原生链接器）来链接 C 函数（参见 Linker::nativeLinker），这是一个符合由运行 JVM 的操作系统和 CPU 决定的 ABI 的 Linker 实现。可以通过以下方式获取暴露 strlen 的 downcall 方法句柄（FunctionDescriptor 的细节将在稍后描述）：
Linker linker = Linker.nativeLinker();
MethodHandle strlen = linker.downcallHandle(
linker.defaultLookup().find("strlen").get(),
FunctionDescriptor.of(JAVA_LONG, ADDRESS)
);
调用向下调用方法句柄将运行 strlen 并使其结果在 Java 中可用。对于 strlen 的参数，我们使用一个辅助方法将 Java 字符串转换为堆外内存段（使用受限的 arena），然后通过引用传递：
try (Arena arena = Arena.openConfined()) {
MemorySegment str = arena.allocateUtf8String("Hello");
long len = strlen.invoke(str); // 5
}
方法句柄在暴露外部函数时表现良好，因为 JVM 已经优化了对方法句柄的调用，直至原生代码级别。当一个方法句柄引用 class 文件中的方法时，调用该方法句柄通常会导致目标方法被 JIT 编译；随后，JVM 通过将控制权转移给为目标方法生成的汇编代码，解释调用 MethodHandle::invokeExact 的 Java 字节码。因此，Java 中的传统方法句柄在幕后指向非 Java 代码；而下调用方法句柄是一种自然的扩展，允许开发者显式地指向非 Java 代码。方法句柄还具备一种称为 签名多态性 的特性，允许使用基本类型参数进行无装箱调用。总之，方法句柄使 Linker 能够以一种自然、高效且可扩展的方式暴露外部函数。
在 Java 中描述 C 类型
要创建一个 downcall 方法句柄，FFM API 要求客户端提供一个 FunctionDescriptor，用于描述目标 C 函数的 C 参数类型和 C 返回类型。在 FFM API 中，C 类型由 MemoryLayout 对象来描述，例如，ValueLayout 用于标量 C 类型，而 GroupLayout 用于 C 结构体类型。客户端通常会手头持有 MemoryLayout 对象，以解引用外部内存中的数据，并可以重用它们来获取 FunctionDescriptor。
FFM API 还使用 FunctionDescriptor 来推导下调方法句柄的类型。每个方法句柄都是强类型的，这意味着它对可以传递给其 invokeExact 方法的参数数量和类型有严格要求。例如，为接受一个 MemorySegment 参数而创建的方法句柄不能通过 invokeExact(<MemorySegment>, <MemorySegment>) 调用，即使 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。
如果客户端针对使用诸如 long、int 和 size_t 等标量类型的 C 函数，则必须了解当前平台。这是因为标量 C 类型与布局常量的关联因平台而异。在 Windows/x64 上，C 语言中的 long 与 JAVA_INT 布局相关联，因此所需的 FunctionDescriptor 将是 FunctionDescriptor.of(JAVA_INT, JAVA_INT)，而下调方法句柄的类型将是 Java 签名 int 到 int。
再比如，假设一个下调用方法句柄应该暴露一个接受指针的 void C 函数。在所有平台上，C 指针类型都与预定义布局 ADDRESS 相关联，因此可以通过 FunctionDescriptor.ofVoid(ADDRESS) 获取所需的 FunctionDescriptor。然后，原生链接器会将下调用方法句柄的类型安排为 Java 签名 MemorySegment 到 void。也就是说，MemorySegment 参数可以根据相应函数描述符中指定的布局通过引用传递，或者按值传递。
客户端可以使用 C 语言指针，而无需了解当前平台。客户端不需要知道当前平台上指针的大小，因为 ADDRESS 布局的大小是从当前平台推断出来的，客户端也不需要区分 C 语言指针类型，例如 int* 和 char**。
最后，与 JNI 不同，本地链接器支持将结构化数据传递给外部函数。假设一个 downcall 方法句柄应该暴露一个接受结构体的 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 会将 downcall 方法句柄的类型安排为从 MemorySegment 到 void 的 Java 签名。
与 C 结构类型关联的内存布局必须是复合布局，该布局定义了 C 结构中所有字段的子布局，包括任何平台相关的填充（原生编译器可能会插入的）。
如果一个 C 函数返回一个按值传递的结构体（此处未展示），那么必须在堆外分配一段新的内存，并将其返回给 Java 客户端。为了实现这一点，downcallHandle 返回的方法句柄需要一个额外的 SegmentAllocator 参数，FFM API 使用该参数来分配一个内存段，用于保存 C 函数返回的结构体。
如前所述，虽然原生链接器实现专注于提供 Java 和 C 库之间的互操作性，但 Linker 接口是与语言无关的：它对 C 语言类型的定义没有特定的知识，因此客户端需要负责获取适合的 C 类型布局定义。这一选择是经过深思熟虑的，因为 C 类型的布局定义（无论是简单的标量还是复杂的结构体）最终都依赖于平台，因此可以由一个对该目标平台有深入了解的工具自动生成。
为 C 函数打包 Java 参数
调用约定 通过指定一种语言中的代码如何调用另一种语言中的函数、传递参数以及接收结果，从而实现不同语言之间的互操作。Linker API 在调用约定方面是中立的，但原生链接器实现开箱即用地支持多种调用约定：Linux/x64、Linux/AArch64、macOS/x64、macOS/AArch64 和 Windows/x64。由于它是用 Java 编写的，因此比 JNI 更容易维护和扩展，JNI 的调用约定是硬编码到 HotSpot 的 C++ 代码中的。
考虑上面获得的 SYSTEMTIME 结构/布局的 FunctionDescriptor。根据运行 JVM 的操作系统和 CPU 的调用约定，本地链接器使用 FunctionDescriptor 来推断当使用 MemorySegment 参数调用 downcall 方法句柄时，应该如何将结构的字段传递给 C 函数。对于一种调用约定，本地链接器实现可以安排分解传入的内存段，使用通用 CPU 寄存器传递前四个字段，并在 C 栈上传递剩余的字段。对于另一种调用约定，本地链接器实现可以安排通过分配一块内存区域来间接传递该结构，将传入内存段的内容批量复制到该区域中，并将指向该区域的指针传递给 C 函数。这种最低级别的参数打包是在幕后进行的，不需要客户端代码的任何监督。
零长度内存段
外部函数通常会分配一块内存区域，并返回指向该区域的指针。使用内存段来建模这样的区域具有挑战性，因为该区域的大小对 Java 运行时不可用。例如，返回类型为 char* 的 C 函数可能会返回指向包含单个 char 值的区域的指针，或者返回指向以 '\0' 结尾的 char 值序列的区域的指针。调用外部函数的代码无法直接获知该区域的大小。
FFM API 将从外部函数返回的指针表示为零长度内存段。该段的地址是指针的值，而该段的大小为零。同样，当客户端从内存段读取地址时，将返回零长度的内存段。
零长度的段具有微不足道的空间边界，因此任何访问此类段的尝试都会因 IndexOutOfBoundsException 而失败。这是一个关键的安全特性：由于这些段关联的内存区域大小未知，涉及这些段的访问操作无法被验证。实际上，零长度的内存段包装了一个地址，并且不能在没有明确意图的情况下使用。
客户端有两种方式可以访问原生的零长度内存段，但这两者都不安全：
-
客户端可以将一个原始内存地址（例如，
long值）通过MemorySegment::ofAddress工厂方法包装为指定大小的段。该工厂方法会为原本未加工的内存地址附加新的空间和时间边界，以允许解引用操作。此工厂返回的内存段是不安全的：一个原始内存地址可能与一个 10 字节长的内存区域相关联，但客户端可能高估了该区域的大小并创建了一个 100 字节长的内存段。这之后可能会导致尝试访问超出该区域边界的内存，从而引发 JVM 崩溃，或者更糟糕的是，导致悄无声息的内存损坏。 -
另一种方式是，客户端可以通过
ValueLayout.OfAddress::asUnbounded方法获取一个 无界 的地址值布局。当访问操作使用无界地址值布局时，FFM API 会将对应的原始内存地址视为具有最大尺寸（即java.lang.Long.MAX_VALUE）的本地段。因此，可以直接访问该本地段。
由于这些访问原生零长度内存段的方式并不安全，因此在程序中使用它们会导致 Java 运行时发出警告（更多信息请参见下文）。
回调
有时，将 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().find("qsort").get(),
FunctionDescriptor.ofVoid(ADDRESS, JAVA_LONG, JAVA_LONG, ADDRESS)
);
和之前一样，我们使用 JAVA_LONG 布局来映射 C 语言中的 size_t 类型，并且对第一个指针参数（数组指针）和最后一个参数（函数指针）都使用 ADDRESS 布局。
qsort 使用作为函数指针传入的自定义比较器函数 compar 对数组的内容进行排序。因此，要调用 downcall 方法句柄，我们需要一个函数指针作为最后一个参数传递给方法句柄的 invokeExact 方法。Linker::upcallStub 帮助我们通过使用现有的方法句柄创建函数指针，如下所示。
首先，我们在 Java 中编写一个 static 方法，该方法比较两个由 MemorySegment 对象间接表示的 int 值：
class Qsort {
static int qsortCompare(MemorySegment elem1, MemorySegment elem2) {
return Integer.compare(elem1.get(JAVA_INT, 0), elem2.get(JAVA_INT, 0));
}
}
第二，我们创建一个指向 Java 比较器方法的方法句柄：
MethodHandle comparHandle
= MethodHandles.lookup()
.findStatic(Qsort.class, "qsortCompare",
MethodType.methodType(int.class,
MemorySegment.class,
MemorySegment.class));
第三，现在我们已经为 Java 比较器获取了方法句柄，可以使用 Linker::upcallStub 创建一个函数指针。与向下调用（downcalls）一样，我们使用 FunctionDescriptor 来描述函数指针的签名：
MemorySegment comparFunc =
linker.upcallStub(comparHandle,
/* A Java description of a C function
implemented by a Java method! */
FunctionDescriptor.of(JAVA_INT, ADDRESS.asUnbounded(), ADDRESS.asUnbounded()),
SegmentScope.auto());
);
我们最终得到了一个内存段 comparFunc，它指向一个可以用来调用我们的 Java 比较器函数的存根，因此我们现在已具备调用 qsort 下行调用句柄所需的全部条件：
try (Arena arena = Arena.openConfined()) {
MemorySegment array = arena.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 代码可以通过指定与底层外部函数类型不兼容的参数类型来请求一个 downcall 方法句柄。在 Java 中调用该 downcall 方法句柄将导致与在 JNI 中调用 native 方法时相同的结果 —— 虚拟机崩溃或未定义行为。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。例如，像 newDirectByteBuffer 这样的不安全 JNI 函数可能会默认被禁用，就像 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 本地方法一样高效且可优化。
依赖
-
外部函数和内存 API 可以以一种更通用、更高效的方式访问非易失性内存，这在之前已经可以通过 JEP 352（非易失性映射字节缓冲区） 实现。
-
此处描述的工作可能会推动后续工作提供一个工具 jextract，该工具从给定的本地库的头文件出发，自动生成与该库进行互操作所需的本地方法句柄。这将大大减少从 Java 中使用本地库的开销。