JNI/NDK開發指南（五）——訪問數組（基本類型數組與對象數組）

JNI中的數組分爲基本類型數組和對象數組，它們的處理方式是不同的，基本類型數組中的全部元素都是JNI的基本數據類型，能夠直接訪問。而對象數組中的全部元素是一個類的實例或其它數組的引用，和字符串操做同樣，不能直接訪問Java傳遞給JNI層的數組，必須選擇合適的JNI函數來訪問和設置Java層的數組對象。閱讀此文假設你已經瞭解了JNI與Java數據類型的映射關係，若是還不瞭解的童鞋，請移步《JNI/NDK開發指南（三）——JNI數據類型及與Java數據類型的映射關係》閱讀。下面以int類型爲例說明基本數據類型數組的訪問方式，對象數組類型用一個建立二維數組的例子來演示如何訪問：

1、訪問基本類型數組

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個參數是拷貝目的地。下圖是計算結果：

在前面的例子當中，咱們經過調用GetIntArrayRegion函數，將int數組中的全部元素拷貝到C臨時緩衝區中，而後在本地代碼中訪問緩衝區中的元素來實現求和的計算，JNI還提供了一個和GetIntArrayRegion相對應的函SetIntArrayRegion，本地代碼能夠經過這個函數來修改全部基本數據類型數組的元素。另外JNI還提供一系列直接獲取數組元素指針的函數Get/Release<Type>ArrayElements，好比：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/Release<type>ArrayElements系列函數永遠是安全的，JVM會選擇性的返回一個指針，這個指針可能指向原始數據，也可能指向原始數據的複製。

2、訪問對象數組

       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;
}
結果：

     本地函數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就會掛掉。

示例代碼下載地址：https://code.csdn.net/xyang81/jnilearn