JNI入门之详细介绍

本文主要介绍下 JNI 相关的概念和一些原理,以便对 JNI 有一个整体认识。

jdk 中的 native 接口

翻翻 java 基础类的源码,你会发现很多 native 关键字修饰的方法,比如 Object 类开头就是一个 native 方法:

1
2
3
4
private static native void registerNatives();
static {
registerNatives();
}

它的特点是在 java 源码中只有方法定义,而没有具体的实现。

JNI 介绍

native 关键字和 JNI

java 中可以使用 native 关键字修饰方法,表示该接口为 JNI(Java Native Interface)。利用这种类型的接口,java 代码可以操作使用其他语言(c/c++、汇编语言等)编写的类库。

为什么需要 JNI

在编写程序时,仅使用 java 并不能满足所有场景的需求,比如下面一些场景:

  • 标准的 java 类库不支持平台相关的功能
  • 已经有一个使用其他语言编写的类库,并且希望 java 代码可以直接使用它
  • 希望使用低级别的语言(例如汇编)实现一小部分关键性的代码

JNI 支持的特性

JNI 支持如下特性:

  • 创建、检查和更新 java 对象(包括数组和 string)
  • 调用 java 方法
  • 捕获和抛出异常
  • 加载类并且获取类信息
  • 执行运行时的类型检查

你还可以使用 JNI 的 Invocation API,将任意的本地程序嵌入到 java 虚拟机。这可以在不链接虚拟机源码的情况下,使得现有程序支持 java。

如何编写 JNI

JNI 类型的接口并非没有方法实现,而是接口实现在外部的类库中。实现一个 JNI 接口的流程如下:

  • java 代码中定义 native 方法
  • 生成对应的 c 头文件
  • 编写 c/c++ 实现
  • 编译为动态链接库
  • 加载动态链接库,调用 native 方法

详细流程可参考「JNI入门之HelloWorld

JNI 的设计

JNI 接口函数和指针

本地代码(native code)通过调用 JNI 函数来访问 java 虚拟机的功能。而通过接口指针可以访问到 JNI 函数。接口指针(interface pointer)本质上是一个指针,它指向了线程内的另一个指针,该指针指向了一个数组,其中数组中的每一项还是指针,它们分别指向一个个接口函数。每个接口函数都位于数组中预定义好的偏移位置。如下图所示:

接口指针

JNI 接口使用类似 c++ 虚函数表的结构组织起来,这样的好处是将 JNI 的名称空间和本地代码区分开,虚拟机可以很容易地提供多个 JNI 函数表。例如,虚拟机可以支持两种 JNI 函数表:

  • 一个执行比较彻底的非法参数检查,适合于调试
  • 另一个执行 JNI 规范要求的最少的检查,这样更有效率

加载和链接本地方法

可使用 System.loadLibrary 加载本地方法。如下示例定义了一个本地方法 f

1
2
3
4
5
6
7
package pkg;  
class Cls {
native double f(int i, String s);
static {
System.loadLibrary(“pkg_Cls”);
}
}

System.loadLibrary 的参数是要加载的类库的名字,系统根据平台规范将其转换为本地的类库全名,例如,Solaris 平台下名字 pkg_Cls 会转换为 libpkg_Cls.so,Win32 平台下则会转换为 pkg_Cls.dll

开发者可以使用一个类库存储任意数量的类使用的所有本地方法,只有所有这些类使用同一个类加载器即可。虚拟机内部会为每一个类加载器维持一个已加载的本地库列表。开发者需注意选择类库的名字,以减少名称冲突的可能性。

解析本地方法名

本地方法名根据以下规则生成

  • 前缀为 Java_
  • 完全限定的类名(包括包名和类的全路径),中间以 _ 分割
  • 方法名
  • 对于重载的 native 方法,方法名后要再跟上 __参数标签

虚拟机检查在本地库的方法里的方法名是否匹配,它首先查找短名字(不带参数标签),然后查找长名字(带方法标签)。只有当一个本地方法重载了另一个本地方法时才需要使用长名字。本地方法和非本地方法重名是没有问题的,因为非本地方法不会暴露在本地库中。

如下的示例中,本地方法 g 不需要使用长名字解析,因为另外一个方法 g 不是本地方法,也就不会在本地库里。

1
2
3
4
class Cls1 { 
int g(int i);
native int g(double d);
}

为了确保能将所有的 Unicode 字符转换合法 c 函数名,还有一些的转换的规则。例如,使用 _ 替代类的全限定名里的 / 。因为方法名不能以数字开头,需使用转义后的 _0_9 等。

本地方法的参数

JNI 接口指针是本地方法的第一个参数,它的类型是 JNIEnv。第二个参数的类型依赖于本地方法是静态的或者非静态的。对于非静态方法来说,它是一个指向对象的引用。而对于静态方法,则是一个指向 java 类的引用。剩下的参数和 java 方法中的参数对应。本地方法通过返回值将结果传递给调用方。

如下是一个 native 方法

1
2
3
4
5
package pkg;  
class Cls {
native double f(int i, String s);
...
}

它对应的本地 c 函数的长名字是 Java_pkg_Cls_f_ILjava_lang_String_2,如下是使用 c 实现的本地方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
jdouble Java_pkg_Cls_f__ILjava_lang_String_2 ( 
JNIEnv *env, /* 接口指针 */
jobject obj, /* this 对象指针 */
jint i, /* 参数 1 */
jstring s) /* 参数 2 */
{
/* 复制 java 的 String */
const char *str = (*env)->GetStringUTFChars(env, s, 0);

/* 处理 string */
...

/* 处理完毕 */
(*env)->ReleaseStringUTFChars(env, s, str);

return ...
}

注意这里始终通过 env 指针操作 java 对象。如下是一个 c++ 版本的实现,相对来说更加简洁。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
extern "C" /* c 调用约定 */  
jdouble Java_pkg_Cls_f__ILjava_lang_String_2 (
JNIEnv *env, /* 接口指针 */
jobject obj, /* this 对象指针 */
jint i, /* 参数 1 */
jstring s) /* 参数 2 */
{
const char *str = env->GetStringUTFChars(s, 0);

...

env->ReleaseStringUTFChars(s, str);

return ...
}

引用 java 对象

基本类型(例如 int、char 等),在 java 和本地代码使用的是传值方式(直接复制)。另一方面,对于任意的 java 对象,传递的则都是引用。虚拟机需要追踪所有传递给本地代码的对象,以便这些对象不被垃圾收集器回收掉。相反,本地代码必须有一种通知虚拟机的方式,告诉它对象已不再使用。此外,垃圾收集器还必须有能力清理掉本地代码引用的对象。

全局和局部引用

JNI 把本地代码使用的对象引用分为了两类:局部引用和全局引用。局部引用在本地方法调用期间有效,在本地方法调用返回后被自动清理掉。全局引用在显示清理前一直有效。

对象被作为局部引用传递给本地方法,所有的 JNI 函数返回的 java 对象都是局部引用。JNI 允许开发者从局部引用创建全局引用。JNI 函数期望 java 对象既能接收全局引用,也能接收局部引用。本地方法可能会将局部引用或全局引用作为结果返回给虚拟机。

大多数情况下,开发者应该依赖虚拟机在本地方法返回后释放局部引用。然而,有些情况下也需要开发者显示地释放局部引用,例如如下场景:

  • 本地方法访问了一个大的 java 对象,因此为该对象创建了一个局部引用。在调用返回之前,本地方法执行了其他计算逻辑。尽管在剩下的计算中不在需要该对象,由于存在对它的局部引用,使得它不能被垃圾收集器回收。
  • 本地方法创建了大量的局部引用,尽管它们并非在同一时刻使用。虚拟机需要一定大小的空间追踪一个局部引用,创建太多的局部引用可能导致内存溢出。例如,本地方法循环遍历一个大的数组对象,获取每一个成员作为局部引用,然后每次针对一个成员执行操作。在每一次迭代后,程序已经不再需要前面成员的局部引用。

JNI 允许开发者在本地方法的任意位置手动删除局部引用。为了保证开发者能够手动清除局部引用,JNI 不允许创建除了返回结果之外的局部引用。

实现局部引用

为了实现局部引用,java 虚拟机为从 java 到本地方法的每一次转换控制创建一个注册表。注册表将不可移动的局部引用映射到 java 对象,并且确保这些对象不会被执行垃圾回收。所有传递给本地方法的 java 对象(包括从 JNI 函数调用返回的结果)自动地被添加到注册表。这些注册表会在本地方法返回后删除掉,使得里面所有的对象可以被垃圾回收。

有多种方式实现注册表,比如使用 table、linked list 或者 hash table。尽管引用计数可以用来避免在注册表中产生重复项,JNI 实现不必检查和折叠重复项。

注意,本地引用不仅可以保存在本地栈中,本地代码还可以将其保存到全局的或者堆数据结构中。

访问 java 对象

JNI 为全局引用和局部引用提供了丰富的访问器函数,这意味着同一份「本地方法实现」可以在不同的虚拟机上运行,而不管虚拟机内部是如何表示 java 对象的。这是 JNI 可以支持多种虚拟机实现的一个重要原因。

通过不透明的引用使用访问器,比直接访问 c 数据结构的代价要大。但是,在大多数情况下,相比 java 程序员使用可以本地方法完成的不同寻常的工作,这点接口开销可以忽略了。

访问基本类型数组

对于包含了很多基本数据类型的 java 大对象(比如 int 数组和 string)来说,相应开销是难以接受的(例如本地方法执行的是数组计算或矩阵计算)。遍历 java 数组并通过函数调用获取每个元素是非常低效的。

一个解决办法是引入一个概念「pinning」,这样本地方法可以请求虚拟机循环数组元素。本地方法直接获取到元素的直接指针。然而这种方法有两个隐含的要求:

  • 垃圾回收器必须支持 pinning
  • 虚拟机必须在内存中连续放置基础类型数组。尽管对于大多数基础类型数组来说,这是一种很自然的实现方式,boolean 数组却可以实现为压缩的或非压缩的。因此,本地代码还依赖 boolean 数组的布局类型,也就失去了可移植性。

为了解决这两个问题,最终使用了一个妥协的方案:

首先,这里提供一系列的函数用于在 java 数组的一个分段和本地内存缓冲区之间复制基础类型数组。如果本地方法需要访问一个大数组的少量元素,那么可以使用这些方法。

其次,开发者还可以使用另外的一组 pinned-down 版本的函数访问数组元素。需要注意的是,使用这些方法时虚拟机可能需要执行存储分配和复制操作。这些函数是否需要复制数组依赖于虚拟机的实现

  • 如果垃圾收集器支持 pinning,并且数组的内存布局也是本地方法所期望的,则不需要复制
  • 否则,数组会被复制到一个不可移动的内存块(例如在 c 堆中),并且执行必要的格式转换,然后返回指向复制后内存的指针。

最后,还提供了另外一些函数,用于通知虚拟机本地代码已经不再访问数组元素了。当调用这些函数的时候,系统或是解锁数组,或是将原始数组和它的不可移动拷贝解除关系,并释放拷贝。

访问属性和方法

JNI 允许本地代码访问 java 对象的属性以及调用方法。JNI 通过符号名和类型签名识别方法和属性。例如,要调用 cls 类的 f 方法,本地代码首先获取到一个方法 ID

1
jmethodID mid = env->GetMethodID(cls, “f”, “(ILjava/lang/String;)D”);

然后就可以重复使用这个方法 ID,而不需要再次查询

1
jdouble result = env->CallDoubleMethod(obj, mid, 10, str);

即使已经获取到属性或方法的 ID,也不会阻止虚拟机卸载类。在类卸载后,方法和属性的 ID 会变成无效的,因此本地代码需要确保:

  • 保持对类的引用
  • 或者重新获取方法或属性 ID

参考

Java Native Interface Specification

0%