From 40f3271c2dd386878c9a180462c75c890913e9b4 Mon Sep 17 00:00:00 2001
From: Andy McFadden
-
If you want to access an object's field from native code, you would do the following:
@@ -104,7 +104,8 @@ to store this data in a static local structure.
The class references, field IDs, and method IDs are guaranteed valid until the class is unloaded. Classes
are only unloaded if all classes associated with a ClassLoader can be garbage collected,
-which is rare but will not be impossible in our system. The jclassID
+which is rare but will not be impossible in our system. Note however that
+the jclass
is a class reference and must be protected with a call
to NewGlobalRef
(see the next section).
@@ -145,23 +146,25 @@ for an example in our source tree.)
Every object that JNI returns is a "local reference". This means that it's valid for the
duration of the current native method in the current thread.
Even if the object itself continues to live on after the native method returns, the reference is not valid.
-This applies to all sub-classes of jobject, including jclass and jarray.
-(Dalvik VM will warn you about this when -Xcheck:jni is enabled.)
+This applies to all sub-classes of jobject
, including
+jclass
, jstring
, and jarray
.
+(Dalvik VM will warn you about most reference mis-uses when extended JNI
+checks are enabled.)
-If you want to hold on to a reference for a longer period, you must use a "global" reference.
-The NewGlobalRef
function takes the local reference as
-an argument and returns a global one:
+If you want to hold on to a reference for a longer period, you must use
+a "global" reference. The NewGlobalRef
function takes the
+local reference as an argument and returns a global one.
+The global reference is guaranteed to be valid until you call
+DeleteGlobalRef
.
-
jobject* localRef = [...]; -jobject* globalRef; -globalRef = env->NewGlobalRef(localRef); ++This pattern is commonly used when caching copies of class objects obtained +from
FindClass
, e.g.: +jclass* localClass = env->FindClass("MyClass"); +jclass* globalClass = (jclass*) env->NewGlobalRef(localClass);-The global reference is guaranteed to be valid until you call -DeleteGlobalRef
. This pattern is frequently used for -cached copies of class objects obtained fromFindClass
. -
All JNI methods accept both local and global references as arguments. It's possible for references to the same object to have different values; @@ -172,11 +175,11 @@ you must use the
IsSameObject
function. Never compare references with "==" in native code.One consequence of this is that you -must not assume object references are constant +must not assume object references are constant or unique in native code. The 32-bit value representing an object may be different from one invocation of a method to the next, and it's possible that two -different objects could have the same 32-bit value at different times. Do -not use jobjects as keys. +different objects could have the same 32-bit value on consecutive calls. Do +not use
jobject
values as keys.Programmers are required to "not excessively allocate" local references. In practical terms this means that if you're creating large numbers of local references, perhaps while running through an array of @@ -194,8 +197,8 @@ and
GetByteArrayElements
are also not objects. One unusual case deserves separate mention. If you attach a native thread to the VM with AttachCurrentThread, the code you are running will never "return" to the VM until the thread detaches from the VM. Any local -references you create will have to be deleted manually unless the thread -is about to exit or detach. +references you create will have to be deleted manually unless you're going +to detach the thread soon.
@@ -382,7 +385,7 @@ hand to printf or a LOG macro.
Extended Checking
-JNI does very little error checking. Calling
SetFieldInt
+JNI does very little error checking. CallingSetIntField
on an Object field will succeed, even if the field is markedprivate
andfinal
. The goal is to minimize the overhead on the assumption that, if you've written it in native code, @@ -451,7 +454,10 @@ You can load native code from shared libraries with the standard preferred way to get at your native code is:
System.loadLibrary()
from a static class initializer. (See the earlier example, where one is used to call nativeClassInit().) The argument is the "undecorated" library name, e.g. to load "libfubar.so" you would pass in "fubar".
+System.loadLibrary()
from a static class
+initializer. (See the earlier example, where one is used to call
+nativeClassInit()
.) The argument is the "undecorated"
+library name, e.g. to load "libfubar.so" you would pass in "fubar".
jint JNI_OnLoad(JavaVM* vm, void* reserved)
@@ -479,8 +485,8 @@ written in C:
You can also call System.load()
with the full path name of the
-shared library. For Android apps, you can get the full path to the
-application's private data storage area from the context object.
+shared library. For Android apps, you may find it useful to get the full
+path to the application's private data storage area from the context object.
This is the recommended approach, but not the only approach. The VM does not require explicit registration, nor that you provide a -- 2.11.0