JNI 访问数组

JNI 中的数组分为基本类型数组和对象数组，它们的处理方式是不一样的，基本类型数组中的所有元素都是 JNI 的基本数据类型，可以直接访问。而对象数组中的所有元素是一个类的实例或其它数组的引用，和字符串操作一样，不能直接访问 Java 传递给 JNI 层的数组，必须选择合适的 JNI 函数来访问和设置 Java 层的数组对象。阅读此文假设你已经了解了 JNI 与 Java 数据类型的映射关系，如果还不了解的，请移步《JNI——JNI 数据类型与 Java 数据类型的映射关系》阅读。下面以 int 类型为例说明基本数据类型数组的访问方式，对象数组类型用一个创建二维数组的例子来演示如何访问。

访问基本类型数组

package com.study.jnilearn;  

// 访问基本类型数组  
public class IntArray {  

    // 在本地代码中求数组中所有元素的和  
    private native int sumArray(int[] arr);  

    public static void main(String[] args) {  
        IntArray p = new IntArray();  
        int[] arr = new int[10];  
        for (int i = 0; i < arr.length; i++) {  
            arr[i] = i;  
        }  
        int sum = p.sumArray(arr);  
        System.out.println("sum = " + sum);  
    }  

    static {  
        System.loadLibrary("IntArray");  
    }  
}  

本地代码：

/* DO NOT EDIT THIS FILE - it is machine generated */  
#include <jni.h>  
/* Header for class com_study_jnilearn_IntArray */  

#ifndef _Included_com_study_jnilearn_IntArray  
#define _Included_com_study_jnilearn_IntArray  
#ifdef __cplusplus  
extern "C" {  
#endif  
/* 
 * Class:     com_study_jnilearn_IntArray 
 * Method:    sumArray 
 * Signature: ([I)I 
 */  
JNIEXPORT jint JNICALL Java_com_study_jnilearn_IntArray_sumArray  
  (JNIEnv *, jobject, jintArray);  

#ifdef __cplusplus  
}  
#endif  
#endif  

// IntArray.c  
#include "com_study_jnilearn_IntArray.h"  
#include <string.h>  
#include <stdlib.h>  

/* 
 * Class:     com_study_jnilearn_IntArray 
 * Method:    sumArray 
 * Signature: ([I)I 
 */  
JNIEXPORT jint JNICALL Java_com_study_jnilearn_IntArray_sumArray  
(JNIEnv *env, jobject obj, jintArray j_array)  
{  
    jint i, sum = 0;  
    jint *c_array;  
    jint arr_len;  
    //1. 获取数组长度  
    arr_len = (*env)->GetArrayLength(env,j_array);  
    //2. 根据数组长度和数组元素的数据类型申请存放java数组元素的缓冲区  
    c_array = (jint*)malloc(sizeof(jint) * arr_len);  
    //3. 初始化缓冲区  
    memset(c_array,0,sizeof(jint)*arr_len);  
    printf("arr_len = %d ", arr_len);  
    //4. 拷贝Java数组中的所有元素到缓冲区中  
    (*env)->GetIntArrayRegion(env,j_array,0,arr_len,c_array);  
    for (i = 0; i < arr_len; i++) {  
        sum += c_array[i];  //5. 累加数组元素的和  
    }  
    free(c_array);  //6. 释放存储数组元素的缓冲区  
    return sum;  
}  

上例中，在 Java 中定义了一个 sumArray 的 native 方法，参数类型是 int[]，对应 JNI 中 jintArray 类型。在本地代码中，首先通过 JNI的GetArrayLength 函数获取数组的长度，已知数组是 jintArray 类型，可以得出数组的元素类型是 jint，然后根据数组的长度和数组元素类型，申请相应大小的缓冲区。如果缓冲区不大的话，当然也可以直接在栈上申请内存，那样效率更高，但是没那么灵活，因为 Java 数组的大小变了，本地代码也跟着修改。接着调用 GetIntArrayRegion 函数将 Java 数组中的所有元素拷贝到 C 缓冲区中，并累加数组中所有元素的和，最后释放存储 java 数组元素的 C 缓冲区，并返回计算结果。GetIntArrayRegion 函数第 1 个参数是 JNIEnv 函数指针，第 2 个参数是 Java 数组对象，第 3 个参数是拷贝数组的开始索引，第 4 个参数是拷贝数组的长度，第 5 个参数是拷贝目的地。下图是计算结果：

sun=45

arr_len=10

在前面的例子当中，我们通过调用 GetIntArrayRegion 函数，将 int 数组中的所有元素拷贝到 C 临时缓冲区中，然后在本地代码中访问缓冲区中的元素来实现求和的计算，JNI 还提供了一个和 GetIntArrayRegion 相对应的函 SetIntArrayRegion，本地代码可以通过这个函数来修改所有基本数据类型数组的元素。另外 JNI 还提供一系列直接获取数组元素指针的函数 Get/ReleaseArrayElements，比如：GetIntArrayElements、ReleaseArrayElements、GetFloatArrayElements、ReleaseFloatArrayElements 等。下面我们用这种方式重新实现计算数组元素的和：

JNIEXPORT jint JNICALL Java_com_study_jnilearn_IntArray_sumArray2  
(JNIEnv *env, jobject obj, jintArray j_array)  
{  
    jint i, sum = 0;  
    jint *c_array;  
    jint arr_len;  
    // 可能数组中的元素在内存中是不连续的，JVM可能会复制所有原始数据到缓冲区，然后返回这个缓冲区的指针  
    c_array = (*env)->GetIntArrayElements(env,j_array,NULL);  
    if (c_array == NULL) {  
        return 0;   // JVM复制原始数据到缓冲区失败  
    }  
    arr_len = (*env)->GetArrayLength(env,j_array);  
    printf("arr_len = %d\n", arr_len);  
    for (i = 0; i < arr_len; i++) {  
        sum += c_array[i];  
    }  
    (*env)->ReleaseIntArrayElements(env,j_array, c_array, 0); // 释放可能复制的缓冲区  
    return sum;  
} 

GetIntArrayElements 第三个参数表示返回的数组指针是原始数组，还是拷贝原始数据到临时缓冲区的指针，如果是 JNI_TRUE：表示临时缓冲区数组指针，JNI_FALSE：表示临时原始数组指针。开发当中，我们并不关心它从哪里返回的数组指针，这个参数填 NULL 即可，但在获取到的指针必须做校验，因为当原始数据在内存当中不是连续存放的情况下，JVM 会复制所有原始数据到一个临时缓冲区，并返回这个临时缓冲区的指针。有可能在申请开辟临时缓冲区内存空间时，会内存不足导致申请失败，这时会返回 NULL。

写过 Java 的程序员都知道，在 Java 中创建的对象全都由 GC（垃圾回收器）自动回收，不需要像 C/C++ 一样需要程序员自己管理内存。GC 会实时扫描所有创建的对象是否还有引用，如果没有引用则会立即清理掉。当我们创建一个像 int 数组对象的时候，当我们在本地代码想去访问时，发现这个对象正被 GC 线程占用了，这时本地代码会一直处于阻塞状态，直到等待 GC 释放这个对象的锁之后才能继续访问。为了避免这种现象的发生，JNI 提供了 Get/ReleasePrimitiveArrayCritical 这对函数，本地代码在访问数组对象时会暂停 GC 线程。不过使用这对函数也有个限制，在 Get/ReleasePrimitiveArrayCritical 这两个函数期间不能调用任何会让线程阻塞或等待 JVM 中其它线程的本地函数或JNI函数，和处理字符串的 Get/ReleaseStringCritical 函数限制一样。这对函数和 GetIntArrayElements 函数一样，返回的是数组元素的指针。下面用这种方式重新实现上例中的功能：

JNIEXPORT jint JNICALL Java_com_study_jnilearn_IntArray_sumArray  
(JNIEnv *env, jobject obj, jintArray j_array)  
{  
    jint i, sum = 0;  
    jint *c_array;  
    jint arr_len;  
    jboolean isCopy;  
    c_array = (*env)->GetPrimitiveArrayCritical(env,j_array,&isCopy);  
    printf("isCopy: %d \n", isCopy);  
    if (c_array == NULL) {  
        return 0;  
    }  
    arr_len = (*env)->GetArrayLength(env,j_array);  
    printf("arr_len = %d\n", arr_len);  
    for (i = 0; i < arr_len; i++) {  
        sum += c_array[i];  
    }  
    (*env)->ReleasePrimitiveArrayCritical(env, j_array, c_array, 0);  
    return sum;  
}  

小结

• 对于小量的、固定大小的数组，应该选择 Get/SetArrayRegion 函数来操作数组元素是效率最高的。因为这对函数要求提前分配一个 C 临时缓冲区来存储数组元素，你可以直接在 Stack（栈）上或用 malloc 在堆上来动态申请，当然在栈上申请是最快的。有童鞋可能会认为，访问数组元素还需要将原始数据全部拷贝一份到临时缓冲区才能访问而觉得效率低？我想告诉你的是，像这种复制少量数组元素的代价是很小的，几乎可以忽略。这对函数的另外一个优点就是，允许你传入一个开始索引和长度来实现对子数组元素的访问和操作（SetArrayRegion函数可以修改数组），不过传入的索引和长度不要越界，函数会进行检查，如果越界了会抛出 ArrayIndexOutOfBoundsException 异常。
• 如果不想预先分配 C 缓冲区，并且原始数组长度也不确定，而本地代码又不想在获取数组元素指针时被阻塞的话，使用 Get/ReleasePrimitiveArrayCritical 函数对，就像 Get/ReleaseStringCritical 函数对一样，使用这对函数要非常小心，以免死锁。
• Get/ReleaseArrayElements 系列函数永远是安全的，JVM 会选择性的返回一个指针，这个指针可能指向原始数据，也可能指向原始数据的复制。

访问对象数组

JNI 提供了两个函数来访问对象数组，GetObjectArrayElement 返回数组中指定位置的元素，SetObjectArrayElement 修改数组中指定位置的元素。与基本类型不同的是，我们不能一次得到数据中的所有对象元素或者一次复制多个对象元素到缓冲区。因为字符串和数组都是引用类型，只能通过 Get/SetObjectArrayElement 这样的 JNI 函数来访问字符串数组或者数组中的数组元素。下面的例子通过调用一个本地方法来创建一个二维的 int 数组，然后打印这个二维数组的内容：

package com.study.jnilearn;  

public class ObjectArray {  

    private native int[][] initInt2DArray(int size);  

    public static void main(String[] args) {  
        ObjectArray obj = new ObjectArray();  
        int[][] arr = obj.initInt2DArray(3);  
        for (int i = 0; i < 3; i++) {  
            for (int j = 0; j < 3; j++) {  
                System.out.format("arr[%d][%d] = %d\n", i, j, arr[i][j]);  
            }  
        }  
    }  

    static {  
        System.loadLibrary("ObjectArray");  
    }  
}  

本地代码：

/* DO NOT EDIT THIS FILE - it is machine generated */  
#include <jni.h>  
/* Header for class com_study_jnilearn_ObjectArray */  

#ifndef _Included_com_study_jnilearn_ObjectArray  
#define _Included_com_study_jnilearn_ObjectArray  
#ifdef __cplusplus  
extern "C" {  
#endif  
/* 
 * Class:     com_study_jnilearn_ObjectArray 
 * Method:    initInt2DArray 
 * Signature: (I)[[I 
 */  
JNIEXPORT jobjectArray JNICALL Java_com_study_jnilearn_ObjectArray_initInt2DArray  
  (JNIEnv *, jobject, jint);  

#ifdef __cplusplus  
}  
#endif  
#endif  

// ObjectArray.c  

#include "com_study_jnilearn_ObjectArray.h"  
/* 
 * Class:     com_study_jnilearn_ObjectArray 
 * Method:    initInt2DArray 
 * Signature: (I)[[I 
 */  
JNIEXPORT jobjectArray JNICALL Java_com_study_jnilearn_ObjectArray_initInt2DArray  
  (JNIEnv *env, jobject obj, jint size)  
{  
    jobjectArray result;  
    jclass clsIntArray;  
    jint i,j;  
    // 1.获得一个int型二维数组类的引用  
    clsIntArray = (*env)->FindClass(env,"[I");  
    if (clsIntArray == NULL)  
    {  
        return NULL;  
    }  
    // 2.创建一个数组对象（里面每个元素用clsIntArray表示）  
    result = (*env)->NewObjectArray(env,size,clsIntArray,NULL);  
    if (result == NULL)  
    {  
        return NULL;  
    }  

    // 3.为数组元素赋值  
    for (i = 0; i < size; ++i)  
    {  
        jint buff[256];  
        jintArray intArr = (*env)->NewIntArray(env,size);  
        if (intArr == NULL)  
        {  
            return NULL;  
        }  
        for (j = 0; j < size; j++)  
        {  
            buff[j] = i + j;  
        }  
        (*env)->SetIntArrayRegion(env,intArr, 0,size,buff);  
        (*env)->SetObjectArrayElement(env,result, i, intArr);  
        (*env)->DeleteLocalRef(env,intArr);  
    }  

    return result;  
}  

结果：

arr[0][0]=0
arr[0][1]=1
arr[0][2]=2
arr[0][0]=1
arr[0][1]=2
arr[0][2]=3
arr[0][0]=2
arr[0][1]=3
arr[0][2]=4

本地函数 initInt2DArray 首先调用 JNI 函数 FindClass 获得一个 int 型的二维数组类的引用，传递给FindClass 的参数"[I"是 JNI class descript（JNI 类型描述符，后面为详细介绍），它对应着 JVM 中的int[]类型。如果 int[]类加载失败的话，FindClass 会返回 NULL，然后抛出一个java.lang.NoClassDefFoundError: [I异常。

接下来，NewObjectArray 创建一个新的数组，这个数组里面的元素类型用 intArrCls(int[])类型来表示。函数NewObjectArray 只能分配第一维，JVM 没有与多维数组相对应的数据结构，JNI 也没有提供类似的函数来创建二维数组。由于 JNI 中的二维数组直接操作的是 JVM 中的数据结构，相比 JAVA 和 C/C++创建二维数组要复杂很多。给二维数组设置数据的方式也非常直接，首先用 NewIntArray 创建一个 JNI 的 int 数组，并为每个数组元素分配空间，然后用 SetIntArrayRegion 把 buff[]缓冲中的内容复制到新分配的一维数组中去，最后在外层循环中依次将 int[]数组赋值到 jobjectArray 数组中，一维数组中套一维数组，就形成了一个所谓的二维数组。

另外，为了避免在循环内创建大量的 JNI 局部引用，造成 JNI 引用表溢出，所以在外层循环中每次都要调用DeleteLocalRef 将新创建的 jintArray 引用从引用表中移除。在 JNI 中，只有 jobject 以及子类属于引用变量，会占用引用表的空间，jint，jfloat，jboolean 等都是基本类型变量，不会占用引用表空间，即不需要释放。引用表最大空间为 512 个，如果超出这个范围，JVM 就会挂掉。