jni jnienv EnsureLocalCapacity example c c++ java

EnsureLocalCapacity

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);

Ensures that at least a given number of local references can be created in the current thread. Returns 0 on success; otherwise returns a negative number and throws an OutOfMemoryError.

Before it enters a native method, the VM automatically ensures that at least 16 local references can be created.

(EnsureLocalCapacity)For backward compatibility, the VM allocates local references beyond the ensured capacity. (As a debugging support, the VM may give the user warnings that too many local references are being created. In the JDK, the programmer can supply the -verbose:jni command line option to turn on these messages.) The VM calls FatalError if no more local references can be created beyond the ensured capacity.

LINKAGE:

Index 26 in the JNIEnv interface function table.

SINCE:

JDK/JRE 1.2

Example - EnsureLocalCapacity

 /* The number of local references to be created is equal to
    the length of the array. */ 
 if ((*env)->EnsureLocalCapacity(env, len)) < 0) {
     ... /* out of memory */
 }
 for (i = 0; i < len; i++) {
     jstring jstr = (*env)->GetObjectArrayElement(env, arr, i);
     ... /* process jstr */
     /* DeleteLocalRef is no longer necessary */
 }