查看原文
其他

打通 JVM 与 Native 代码:快速了解巴拿马项目

ImportNew 2022-12-31

(给ImportNew加星标,提高Java技能)


随着 JDK 19 在未来几周*内发布,是时候讨论巴拿马(Panama)项目了,更具体地说,是新的外部函数和内存 API,它简化了 Java 和本机代码之间的互操作性。

编注:2022年9月20日 JDK 19 已正式发布。

本文使用一个简单的基于 Java 的“Hello World”应用程序调用一些 C 本机代码来介绍外部函数和内存 API。

准备


要使用 Foreign Function & Memory API 和示例代码,请先下载 JDK 19(build 24 或更高版本)。

项目概述


巴拿马项目旨在为 JVM 和用其他语言(如 C/C++)编写的本机代码之间搭建桥梁。包含以下 3 个部分:

  • 外部函数和内存 API:JEP 424
  • Jextract 工具
  • Vector API:JEP 338

外部函数和内存 API 提供一些重要的抽象:

  • 内存段及其地址:一组 API 类,用于处理本机内存和指向它的指针;
  • 内存布局和描述符:用于模拟外部类型(结构、原语)和函数描述符的 API;
  • 内存会话:管理一个或多个内存资源生命周期的抽象;
  • 链接器和符号查找:一组用于执行向下和向上调用的 API 类;
  • 段分配器:一种用于在内存会话中分配内存段的 API。

Hello World 程序


对巴拿马了解得越深,就越会发现拥有一个好的介绍是至关重要的,这样就不会错过重要的概念、技术和方法。

本文将介绍链接器(Linker),并简要介绍 SymbolLookup 方法和本机内存管理 ( MemorySession )。上面描述的这三个主要组件是构建块,用于更深入地开发由 Java 和本机代码组成的程序。

链接器


从技术角度来看,链接器是两个二进制接口之间的桥梁:JVM 和 C/C++ 本机代码,也称为 C ABI。

JDK 19 为所有流行的平台提供了一组 C ABI 实现:


public static Linker getSystemLinker() { return switch (CABI.current()) { case Win64 - > Windowsx64Linker.getInstance(); case SysV - > SysVx64Linker.getInstance(); case LinuxAArch64 - > LinuxAArch64Linker.getInstance(); case MacOsAArch64 - > MacOsAArch64Linker.getInstance(); };}


在 JDK 术语中,链接器是特定于平台的 C ABI 实现的一个实例。链接器提供一组方法来执行向下调用和向上调用,其中:


  • downcall 是从高级子系统发起的事件。在我们的例子中是 JVM 到较低级别的子系统,如操作系统内核或者一些 Java 代码调用一些本机代码。稍后将通过外部函数和内存 API 说明这一点。

  • upcall  例如一些本机代码调用一些 Java 代码。


虽然链接器就像电话一样,想打电话给谁,只需拨入正确的电话号码即可。符号查找方法就像通讯录,只需提供要打电话的人正确的信息即可。


要执行向下调用,需要提供调用的(本机)函数的描述符、通过符号查找分配的本机地址,以及用于创建调用本机函数的方法句柄对应的链接器。


从 Java 实现经典的 C 风格的 Hello World:


int printf(const char * __restrict, ...)


Java 中的 C 语言风格的“Hello World” 


要编写使用本机 printf 函数的基于 Java 的“Hello World”应用程序,我们需要:

1. 找到 native 函数的地址


首先,我们需要搜索 printf 函数的本机内存地址:


Linker linker = Linker.nativeLinker();SymbolLookup linkerLookup = linker.defaultLookup();SymbolLookup systemLookup = SymbolLookup.loaderLookup();
SymbolLookup symbolLookup = name -> systemLookup.lookup(name).or(() -> linkerLookup.lookup(name));
Optional<MemorySegment> printfMemorySegment = symbolLookup.lookup("printf");

从技术上讲,查找可能会失败,因此需要提供适当的错误处理。

2. 构建正在调用的函数的描述符


一旦知道了 C printf 所在的位置,就需要定义由结果类型和接受的参数组成的 printf 描述符。值得一提的是,像 printf 这样的本机函数称为可变参数函数。在 Java 中,接受可变参数集的方法称为具有可变参数的方法。

为了简化,我们可以为 printf 定义 FunctionDescriptor 的简化版本:


FunctionDescriptor printfDescriptor = FunctionDescriptor.of(JAVA_INT, ADDRESS);

注意:从 Java 运行时的角度来看,C 指针背后的值类型无关紧要,因为 C 指针的内存布局不保存类型,而是平台固定的 32/64 位值。


一个描述符定义了一个返回值类型为 int 的函数,它的参数是一个指针。假设一个描述符几乎对应于它在 stdio.h 中的 C 定义,因为它定义了一个标准函数,而 printf 是一个可变参数函数。


通过值布局(Value Layout)在 Java 中对 C 类型建模


在 Java 中,值布局用于对与基本数据类型的值关联的内存布局建模,例如整数类型(有符号或无符号)和浮点类型。JAVA_INT 和 ADDRESS 都是对应的 C 类型的值布局。


JAVA_INT :


// ValueLayout.OfInt.classOfInt JAVA_INT = new OfInt(ByteOrder.nativeOrder()).withBitAlignment(32);

这是值布局的一个实例,它的载体是 int.class。通过这种布局,链接器被指示在 C int32和具有运营商类 int.class 的相应 Java int 类型之间创建桥梁。

ADDRESS:


// ValueLayout.OfAddress.classOfAddress ADDRESS = new OfAddress(ByteOrder.nativeOrder()) .withBitAlignment(ValueLayout.ADDRESS_SIZE_BITS);

ADDRESS 是一个值布局,其中对应的 C 类型是一个指向变量的指针,载体是MemoryAddress.class。

3. 从函数的本机内存地址构建方法句柄


使用 C printf 本机地址及其函数描述符,我们现在可以为 C printf 创建一个方法句柄:


MethodHandle printfMethodHandle = symbolLookup.lookup("printf").map( addr - > linker.downcallHandle(addr, printfDescriptor)).orElse(null);

上面的代码创建了 C print 的可执行引用,简而言之:一个方法句柄,来自 printf 的本机内存地址及其函数描述符。

注意:方法句柄是对底层方法、构造函数、字段或类似低级操作的类型化、可执行引用,具有参数或返回值的可选转换。

现在已经解释了必要的概念,我们可以扩展 downcalls 和 upcalls 的定义:

  • downcall 是通过由本机函数地址及其 Java 版本的函数描述符形成的 MethodHandle调用本机函数。
  • upcall 是通过 MethodHandle 调用一些用 Java 编写的代码,该 MethodHandle 转换为本机内存段,然后可以将其作为函数指针传递给本机函数。


4. 分配本机内存


我们需要以某种方式将 Java 对象绑定到本机内存段,以确保 C printf 可以访问它们。
C 中的内存分配和释放内存都很痛苦,因为开发人员可能会忘记分配或释放内存,这会导致程序泄漏或因分段错误而崩溃。

另一方面,Java 依靠垃圾收集器来分配和释放内存。但是巴拿马的外部函数和内存 API 是在堆外分配内存,有助于分配堆外内存,这是任何本机互操作的关键部分!

外部函数和内存 API 允许开发人员分配和访问内存段、它们的地址以及位于堆上或堆外的连续内存区域的形状。所有分配的内存段都绑定到特定的内存会话 ( MemorySession )。内存会话的实例提供一组 API 来分配本机内存段。考虑一个内存会话,就像一个统一的内存分配工具,比如 C malloc。MemorySession 实现了 AutoClosable 接口,它使用 try-with-resources 结构极大地简化了取消分配。

外部函数和内存 API 提供了不止一种分配内存段的正确方法。一种可能的本机内存分配方法是 SegmentAllocator,它类似于 MemorySession:


try (var memorySession = MemorySession.openConfined()) { SegmentAllocator allocator = SegmentAllocator.newNativeArena(memorySession); var cStringFromAllocator = allocator.allocateUtf8String("Hello World" + "\n"); var cStringFromSession = memorySession.allocateUtf8String("Hello World" + "\n");}

简单起见,这个“Hello World”应用程序将使用 MemorySession 作为内存段分配工具。

最后,要调用 C printf,我们需要使用 MemorySession 在内存会话中分配 const char * 内存段,并将其传递给 C printf 函数:

MemorySegment cString = memorySession.allocateUtf8String(str + "\n");

使用分配的内存段,我们可以调用函数:

private static int printf(String str, MemorySession memorySession) throws Throwable { Objects.requireNonNull(printfMethodHandle); var cString = memorySession.allocateUtf8String(str + "\n"); return (int) printfMethodHandle.invoke(cString);}
public static void main(String[] args) throws Throwable { var str = "Hello World"; try (var memorySession = MemorySession.openConfined()) { System.out.println(printf(str, memorySession)); }}


5. 小结


到目前为止,我们了解到内存会话 ( MemorySession ) 或段分配器 ( SegmentAllocator ) 是执行内存分配的关键 API。应使用 try-with-resources 声明内存会话以实现隐式内存释放。分配内存段有多种选择——通过段分配器或直接通过内存会话。链接器、符号查找对象、值和内存布局以及方法句柄都是静态对象。

总结

本文概述了外部函数和内存 API,并研究了如何从 Java 调用简单的 C 函数。
好消息是开发人员可以依靠 jextract 工具来处理大部分外部函数和内存机制。

使用外部函数和内存 API 从 Java 调用本机代码时需要解决几个问题:

  • 获取本机库及其对应的头文件。
  • 在 Java 中构建函数描述符 ( FunctionDescriptor )。
  • 查找函数符号的本机内存地址,并为其创建方法句柄。
  • 创建一个相关的方法句柄并确认它已经正确创建(例如,如果本机库不在系统路径中,查找将失败并且返回一个方法句柄将为空)。
  • 决定应用程序将如何分配内存段:通过段分配器或内存会话。确保内存分配技术在应用程序的整个代码库中保持一致。


代码清单


可以在这里找到本文的资源。

https://github.com/denismakogon/openjdk-project-samples/blob/master/Panama.md#openjdk-panama-part-1

package com.java_devrel.samples.panama.part_1;import java.lang.foreign.*;import java.lang.invoke.MethodHandle;import java.util.Objects;import static java.lang.foreign.ValueLayout.ADDRESS;import static java.lang.foreign.ValueLayout.JAVA_INT;public class PrintfSimplified { private static final Linker linker = Linker.nativeLinker(); private static final SymbolLookup linkerLookup = linker.defaultLookup(); private static final SymbolLookup systemLookup = SymbolLookup.loaderLookup(); private static final SymbolLookup symbolLookup = name - > systemLookup.lookup(name).or(() - > linkerLookup.lookup(name)); private static final FunctionDescriptor printfDescriptor = FunctionDescriptor.of(JAVA_INT.withBitAlignment(32), ADDRESS.withBitAlignment(64)); private static final MethodHandle printfMethodHandle = symbolLookup.lookup("printf").map(addr - > linker.downcallHandle(addr, printfDescriptor)).orElse(null); private static int printf(String str, MemorySession memorySession) throws Throwable { Objects.requireNonNull(printfMethodHandle); var cString = memorySession.allocateUtf8String(str + "\n"); return (int) printfMethodHandle.invoke(cString); } public static void main(String[] args) throws Throwable { var str = "hello world"; try (var memorySession = MemorySession.openConfined()) { System.out.println(printf(str, memorySession)); } }}

转自:Denys Makogon,

链接:denismakogon.github.io/openjdk/panama/2022/05/31/introduction-to-project-panama-part-1.html



- EOF -

推荐阅读  点击标题可跳转

1、JVM问题分析调优经验

2、JDK 19 / Java 19正式GA

3、JVM 解剖公园(12): 本地内存跟踪


看完本文有收获?请转发分享给更多人

关注「ImportNew」,提升Java技能

点赞和在看就是最大的支持❤️


您可能也对以下帖子感兴趣

文章有问题?点此查看未经处理的缓存