diff options
| author | Elliott Hughes <enh@google.com> | 2011-04-14 11:52:03 -0700 |
|---|---|---|
| committer | Elliott Hughes <enh@google.com> | 2011-04-14 11:52:03 -0700 |
| commit | 80aedd4dfc1252cb214fdff5baeb55166e3bf021 (patch) | |
| tree | 36e2bc29569a17575e411ea12978067e4e9c65ca /docs | |
| parent | e71474621b968a9bc649d067155d31213f5764a9 (diff) | |
| download | android_dalvik-80aedd4dfc1252cb214fdff5baeb55166e3bf021.tar.gz android_dalvik-80aedd4dfc1252cb214fdff5baeb55166e3bf021.tar.bz2 android_dalvik-80aedd4dfc1252cb214fdff5baeb55166e3bf021.zip | |
The jni-tips documentation has moved to frameworks/base.
Change-Id: I77fbc3ed593c51f61de9590beaadaa52f08387f8
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/embedded-vm-control.html | 3 | ||||
| -rw-r--r-- | docs/jni-tips.html | 770 |
2 files changed, 0 insertions, 773 deletions
diff --git a/docs/embedded-vm-control.html b/docs/embedded-vm-control.html index a0bdd292b..5c444de70 100644 --- a/docs/embedded-vm-control.html +++ b/docs/embedded-vm-control.html @@ -87,9 +87,6 @@ property. The value set for <code>dalvik.vm.jniopts</code> will be passed in as the <code>-Xjniopts</code> argument. For example: <pre>adb shell setprop dalvik.vm.jniopts forcecopy</pre> -<p>For more information about JNI checks, see -<a href="jni-tips.html">JNI Tips</a>. - <h2><a name="assertions">Assertions</a></h2> diff --git a/docs/jni-tips.html b/docs/jni-tips.html deleted file mode 100644 index c01c107ad..000000000 --- a/docs/jni-tips.html +++ /dev/null @@ -1,770 +0,0 @@ -<html> - <head> - <title>Android JNI Tips</title> - <link rel=stylesheet href="android.css"> - </head> - - <body> - <h1><a name="JNI_Tips"></a>Android JNI Tips</h1> -<p> -</p><p> -</p><ul> -<li> <a href="#What_s_JNI_">What's JNI?</a> -</li> -<li> <a href="#JavaVM_and_JNIEnv">JavaVM and JNIEnv</a> -</li> -<li> <a href="#Threads">Threads</a> -</li> -<li> <a href="#jclass_jmethodID_and_jfieldID">jclass, jmethodID, and jfieldID</a> -</li> -<li> <a href="#local_vs_global_references">Local vs. Global References</a> -</li> -<li> <a href="#UTF_8_and_UTF_16_strings">UTF-8 and UTF-16 Strings</a> -</li> -<li> <a href="#Arrays">Primitive Arrays</a> -</li> -<li> <a href="#RegionCalls">Region Calls</a> -</li> -<li> <a href="#Exceptions">Exceptions</a> -</li> - -<li> <a href="#Extended_checking">Extended Checking</a> -</li> -<li> <a href="#Native_Libraries">Native Libraries</a> -</li> -<li> <a href="#64bit">64-bit Considerations</a> -</li> - -<li> <a href="#Unsupported">Unsupported Features</a> -</li> - -<li> <a href="#FAQUnsatisfied">FAQ: UnsatisfiedLinkError</a> -</li> -<li> <a href="#FAQFindClass">FAQ: FindClass didn't find my class</a> -</li> -<li> <a href="#FAQSharing">FAQ: Sharing raw data with native code</a> -</li> - -</ul> -<p> -<noautolink> -</noautolink></p><p> -</p><h2><a name="What_s_JNI_"> </a> What's JNI? </h2> -<p> - -JNI is the Java Native Interface. It defines a way for code written in the -Java programming language to interact with native -code, e.g. functions written in C/C++. It's VM-neutral, has support for loading code from -dynamic shared libraries, and while cumbersome at times is reasonably efficient. -</p><p> -You really should read through the -<a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/jniTOC.html">JNI spec for J2SE 1.6</a> -to get a sense for how JNI works and what features are available. Some -aspects of the interface aren't immediately obvious on -first reading, so you may find the next few sections handy. -The more detailed <i>JNI Programmer's Guide and Specification</i> can be found -<a href="http://java.sun.com/docs/books/jni/html/jniTOC.html">here</a>. -</p><p> -</p><p> -</p><h2><a name="JavaVM_and_JNIEnv"> </a> JavaVM and JNIEnv </h2> -<p> -JNI defines two key data structures, "JavaVM" and "JNIEnv". Both of these are essentially -pointers to pointers to function tables. (In the C++ version, it's a class whose sole member -is a pointer to a function table.) The JavaVM provides the "invocation interface" functions, -which allow you to create and destroy the VM. In theory you can have multiple VMs per process, -but Android's VM only allows one. -</p><p> -The JNIEnv provides most of the JNI functions. Your native functions all receive a JNIEnv as -the first argument. -</p><p> - -On some VMs, the JNIEnv is used for thread-local storage. For this reason, <strong>you cannot share a JNIEnv between threads</strong>. -If a piece of code has no other way to get its JNIEnv, you should share -the JavaVM, and use JavaVM->GetEnv to discover the thread's JNIEnv. -</p><p> -The C declarations of JNIEnv and JavaVM are different from the C++ -declarations. "jni.h" provides different typedefs -depending on whether it's included into ".c" or ".cpp". For this reason it's a bad idea to -include JNIEnv arguments in header files included by both languages. (Put another way: if your -header file requires "#ifdef __cplusplus", you may have to do some extra work if anything in -that header refers to JNIEnv.) - -</p><p> -</p><h2><a name="Threads"> Threads </a></h2> -<p> -All VM threads are Linux threads, scheduled by the kernel. They're usually -started using Java language features (notably <code>Thread.start()</code>), -but they can also be created elsewhere and then attached to the VM. For -example, a thread started with <code>pthread_create</code> can be attached -with the JNI <code>AttachCurrentThread</code> or -<code>AttachCurrentThreadAsDaemon</code> functions. Until a thread is -attached to the VM, it has no JNIEnv, and -<strong>cannot make JNI calls</strong>. -</p><p> -Attaching a natively-created thread causes the VM to allocate and initialize -a <code>Thread</code> object, add it to the "main" <code>ThreadGroup</code>, -and add the thread to the set that is visible to the debugger. Calling -<code>AttachCurrentThread</code> on an already-attached thread is a no-op. -</p><p> -The Dalvik VM does not suspend threads executing native code. If -garbage collection is in progress, or the debugger has issued a suspend -request, the VM will pause the thread the next time it makes a JNI call. -</p><p> -Threads attached through JNI <strong>must call -<code>DetachCurrentThread</code> before they exit</strong>. -If coding this directly is awkward, in Android >= 2.0 you -can use <code>pthread_key_create</code> to define a destructor -function that will be called before the thread exits, and -call <code>DetachCurrentThread</code> from there. (Use that -key with <code>pthread_setspecific</code> to store the JNIEnv in -thread-local-storage; that way it'll be passed into your destructor as -the argument.) - - -</p><h2><a name="jclass_jmethodID_and_jfieldID"> jclass, jmethodID, and jfieldID </a></h2> -<p> -If you want to access an object's field from native code, you would do the following: -</p><p> -</p><ul> -<li> Get the class object reference for the class with <code>FindClass</code> -</li> -<li> Get the field ID for the field with <code>GetFieldID</code> -</li> -<li> Get the contents of the field with something appropriate, e.g. -<code>GetIntField</code> -</li> -</ul> -<p> -Similarly, to call a method, you'd first get a class object reference and then a method ID. The IDs are often just -pointers to internal VM data structures. Looking them up may require several string -comparisons, but once you have them the actual call to get the field or invoke the method -is very quick. -</p><p> -If performance is important, it's useful to look the values up once and cache the results -in your native code. Because we are limiting ourselves to one VM per process, it's reasonable -to store this data in a static local structure. -</p><p> -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. Note however that -the <code>jclass</code> -is a class reference and <strong>must be protected</strong> with a call -to <code>NewGlobalRef</code> (see the next section). -</p><p> -If you would like to cache the IDs when a class is loaded, and automatically re-cache them -if the class is ever unloaded and reloaded, the correct way to initialize -the IDs is to add a piece of code that looks like this to the appropriate class: -</p><p> - -</p><pre> /* - * We use a class initializer to allow the native code to cache some - * field offsets. - */ - - /* - * A native function that looks up and caches interesting - * class/field/method IDs for this class. Returns false on failure. - */ - native private static boolean nativeClassInit(); - - /* - * Invoke the native initializer when the class is loaded. - */ - static { - if (!nativeClassInit()) - throw new RuntimeException("native init failed"); - } -</pre> -<p> -Create a nativeClassInit method in your C/C++ code that performs the ID lookups. The code -will be executed once, when the class is initialized. If the class is ever unloaded and -then reloaded, it will be executed again. (See the implementation of java.io.FileDescriptor -for an example in our source tree.) -</p><p> -</p><p> -</p><p> -</p><h2><a name="local_vs_global_references"> Local vs. Global References </a></h2> -<p> -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. -<strong>Even if the object itself continues to live on after the native method returns, the reference is not valid.</strong> -This applies to all sub-classes of <code>jobject</code>, including -<code>jclass</code>, <code>jstring</code>, and <code>jarray</code>. -(Dalvik VM will warn you about most reference mis-uses when extended JNI -checks are enabled.) -</p><p> - -If you want to hold on to a reference for a longer period, you must use -a "global" reference. The <code>NewGlobalRef</code> function takes the -local reference as an argument and returns a global one. -The global reference is guaranteed to be valid until you call -<code>DeleteGlobalRef</code>. - -</p><p> -This pattern is commonly used when caching copies of class objects obtained -from <code>FindClass</code>, e.g.: -<p><pre>jclass* localClass = env->FindClass("MyClass"); -jclass* globalClass = (jclass*) env->NewGlobalRef(localClass); -</pre> - -</p><p> -All JNI methods accept both local and global references as arguments. -It's possible for references to the same object to have different values; -for example, the return values from consecutive calls to -<code>NewGlobalRef</code> on the same object may be different. -<strong>To see if two references refer to the same object, -you must use the <code>IsSameObject</code> function.</strong> Never compare -references with "==" in native code. -</p><p> -One consequence of this is that you -<strong>must not assume object references are constant or unique</strong> -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 on consecutive calls. Do -not use <code>jobject</code> values as keys. -</p><p> -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 -Objects, you should free them manually with -<code>DeleteLocalRef</code> instead of letting JNI do it for you. The -VM is only required to reserve slots for -16 local references, so if you need more than that you should either delete as you go or use -<code>EnsureLocalCapacity</code> to reserve more. -</p><p> -Note: method and field IDs are just 32-bit identifiers, not object -references, and should not be passed to <code>NewGlobalRef</code>. The raw data -pointers returned by functions like <code>GetStringUTFChars</code> -and <code>GetByteArrayElements</code> are also not objects. -</p><p> -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 you're going -to detach the thread soon. -</p><p> -</p><p> -</p><p> -</p><h2><a name="UTF_8_and_UTF_16_strings"> </a> UTF-8 and UTF-16 Strings </h2> -<p> -The Java programming language uses UTF-16. For convenience, JNI provides methods that work with "modified UTF-8" encoding -as well. (Some VMs use the modified UTF-8 internally to store strings; ours do not.) The -modified encoding only supports the 8- and 16-bit forms, and stores ASCII NUL values in a 16-bit encoding. -The nice thing about it is that you can count on having C-style zero-terminated strings, -suitable for use with standard libc string functions. The down side is that you cannot pass -arbitrary UTF-8 data into the VM and expect it to work correctly. -</p><p> -It's usually best to operate with UTF-16 strings. With our current VMs, the -<code>GetStringChars</code> method -does not require a copy, whereas <code>GetStringUTFChars</code> requires a malloc and a UTF conversion. Note that -<strong>UTF-16 strings are not zero-terminated</strong>, and \u0000 is allowed, -so you need to hang on to the string length as well as -the string pointer. - -</p><p> -<strong>Don't forget to Release the strings you Get</strong>. The -string functions return <code>jchar*</code> or <code>jbyte*</code>, which -are C-style pointers to primitive data rather than local references. They -are guaranteed valid until Release is called, which means they are not -released when the native method returns. -</p><p> -<strong>Data passed to NewStringUTF must be in "modified" UTF-8 format</strong>. A -common mistake is reading character data from a file or network stream -and handing it to <code>NewStringUTF</code> without filtering it. -Unless you know the data is 7-bit ASCII, you need to strip out high-ASCII -characters or convert them to proper "modified" UTF-8 form. If you don't, -the UTF-16 conversion will likely not be what you expect. The extended -JNI checks will scan strings and warn you about invalid data, but they -won't catch everything. -</p><p> -</p><p> - - -</p><h2><a name="Arrays"> </a> Primitive Arrays </h2> -<p> -JNI provides functions for accessing the contents of array objects. -While arrays of objects must be accessed one entry at a time, arrays of -primitives can be read and written directly as if they were declared in C. -</p><p> -To make the interface as efficient as possible without constraining -the VM implementation, -the <code>Get<PrimitiveType>ArrayElements</code> family of calls -allows the VM to either return a pointer to the actual elements, or -allocate some memory and make a copy. Either way, the raw pointer returned -is guaranteed to be valid until the corresponding <code>Release</code> call -is issued (which implies that, if the data wasn't copied, the array object -will be pinned down and can't be relocated as part of compacting the heap). -<strong>You must Release every array you Get.</strong> Also, if the Get -call fails, you must ensure that your code doesn't try to Release a NULL -pointer later. -</p><p> -You can determine whether or not the data was copied by passing in a -non-NULL pointer for the <code>isCopy</code> argument. This is rarely -useful. -</p><p> -The <code>Release</code> call takes a <code>mode</code> argument that can -have one of three values. The actions performed by the VM depend upon -whether it returned a pointer to the actual data or a copy of it: -<ul> - <li><code>0</code> - <ul> - <li>Actual: the array object is un-pinned. - <li>Copy: data is copied back. The buffer with the copy is freed. - </ul> - <li><code>JNI_COMMIT</code> - <ul> - <li>Actual: does nothing. - <li>Copy: data is copied back. The buffer with the copy - <strong>is not freed</strong>. - </ul> - <li><code>JNI_ABORT</code> - <ul> - <li>Actual: the array object is un-pinned. Earlier - writes are <strong>not</strong> aborted. - <li>Copy: the buffer with the copy is freed; any changes to it are lost. - </ul> -</ul> -</p><p> -One reason for checking the <code>isCopy</code> flag is to know if -you need to call <code>Release</code> with <code>JNI_COMMIT</code> -after making changes to an array — if you're alternating between making -changes and executing code that uses the contents of the array, you may be -able to -skip the no-op commit. Another possible reason for checking the flag is for -efficient handling of <code>JNI_ABORT</code>. For example, you might want -to get an array, modify it in place, pass pieces to other functions, and -then discard the changes. If you know that JNI is making a new copy for -you, there's no need to create another "editable" copy. If JNI is passing -you the original, then you do need to make your own copy. -</p><p> -Some have asserted that you can skip the <code>Release</code> call if -<code>*isCopy</code> is false. This is not the case. If no copy buffer was -allocated, then the original memory must be pinned down and can't be moved by -the garbage collector. -</p><p> -Also note that the <code>JNI_COMMIT</code> flag does NOT release the array, -and you will need to call <code>Release</code> again with a different flag -eventually. -</p><p> -</p><p> - - -</p><h2><a name="RegionCalls"> Region Calls </a></h2> - -<p> -There is an alternative to calls like <code>Get<Type>ArrayElements</code> -and <code>GetStringChars</code> that may be very helpful when all you want -to do is copy data in or out. Consider the following: -<pre> - jbyte* data = env->GetByteArrayElements(array, NULL); - if (data != NULL) { - memcpy(buffer, data, len); - env->ReleaseByteArrayElements(array, data, JNI_ABORT); - } -</pre> -<p> -This grabs the array, copies the first <code>len</code> byte -elements out of it, and then releases the array. Depending upon the VM -policies the <code>Get</code> call will either pin or copy the array contents. -We copy the data (for perhaps a second time), then call Release; in this case -we use <code>JNI_ABORT</code> so there's no chance of a third copy. -</p><p> -We can accomplish the same thing with this: -<pre> - env->GetByteArrayRegion(array, 0, len, buffer); -</pre> -</p><p> -This has several advantages: -<ul> - <li>Requires one JNI call instead of 2, reducing overhead. - <li>Doesn't require pinning or extra data copies. - <li>Reduces the risk of programmer error — no risk of forgetting - to call <code>Release</code> after something fails. -</ul> -</p><p> -Similarly, you can use the <code>Set<Type>ArrayRegion</code> call -to copy data into an array, and <code>GetStringRegion</code> or -<code>GetStringUTFRegion</code> to copy characters out of a -<code>String</code>. - - -</p><h2><a name="Exceptions"> Exceptions </a></h2> -<p> -<strong>You may not call most JNI functions while an exception is pending.</strong> -Your code is expected to notice the exception (via the function's return value, -<code>ExceptionCheck()</code>, or <code>ExceptionOccurred()</code>) and return, -or clear the exception and handle it. -</p><p> -The only JNI functions that you are allowed to call while an exception is -pending are: -<font size="-1"><ul> - <li>DeleteGlobalRef - <li>DeleteLocalRef - <li>DeleteWeakGlobalRef - <li>ExceptionCheck - <li>ExceptionClear - <li>ExceptionDescribe - <li>ExceptionOccurred - <li>MonitorExit - <li>PopLocalFrame - <li>PushLocalFrame - <li>Release<PrimitiveType>ArrayElements - <li>ReleasePrimitiveArrayCritical - <li>ReleaseStringChars - <li>ReleaseStringCritical - <li>ReleaseStringUTFChars -</ul></font> -</p><p> -Many JNI calls can throw an exception, but often provide a simpler way -of checking for failure. For example, if <code>NewString</code> returns -a non-NULL value, you don't need to check for an exception. However, if -you call a method (using a function like <code>CallObjectMethod</code>), -you must always check for an exception, because the return value is not -going to be valid if an exception was thrown. -</p><p> -Note that exceptions thrown by interpreted code do not "leap over" native code, -and C++ exceptions thrown by native code are not handled by Dalvik. -The JNI <code>Throw</code> and <code>ThrowNew</code> instructions just -set an exception pointer in the current thread. Upon returning to the VM from -native code, the exception will be noted and handled appropriately. -</p><p> -Native code can "catch" an exception by calling <code>ExceptionCheck</code> or -<code>ExceptionOccurred</code>, and clear it with -<code>ExceptionClear</code>. As usual, -discarding exceptions without handling them can lead to problems. -</p><p> -There are no built-in functions for manipulating the Throwable object -itself, so if you want to (say) get the exception string you will need to -find the Throwable class, look up the method ID for -<code>getMessage "()Ljava/lang/String;"</code>, invoke it, and if the result -is non-NULL use <code>GetStringUTFChars</code> to get something you can -hand to printf or a LOG macro. - -</p><p> -</p><p> -</p><h2><a name="Extended_checking"> Extended Checking </a></h2> -<p> -JNI does very little error checking. Calling <code>SetIntField</code> -on an Object field will succeed, even if the field is marked -<code>private</code> and <code>final</code>. The -goal is to minimize the overhead on the assumption that, if you've written it in native code, -you probably did it for performance reasons. -</p><p> -In Dalvik, you can enable additional checks by setting the -"<code>-Xcheck:jni</code>" flag. If the flag is set, the VM directs -the JavaVM and JNIEnv pointers to a different table of functions. -These functions perform an extended series of checks before calling the -standard implementation. - -</p><p> -The additional tests include: -</p><p> -</p> -<ul> -<li> Check for null pointers where not allowed. -</li> -<li> Verify argument type correctness (jclass is a class object, -jfieldID points to field data, jstring is a java.lang.String). -</li> -<li> Field type correctness, e.g. don't store a HashMap in a String field. -</li> -<li> Ensure jmethodID is appropriate when making a static or virtual -method call. -</li> -<li> Check to see if an exception is pending on calls where pending exceptions are not legal. -</li> -<li> Check for calls to inappropriate functions between Critical get/release calls. -</li> -<li> Check that JNIEnv structs aren't being shared between threads. - -</li> -<li> Make sure local references aren't used outside their allowed lifespan. -</li> -<li> UTF-8 strings contain only valid "modified UTF-8" data. -</li> -</ul> -<p>Accessibility of methods and fields (i.e. public vs. private) is not -checked. -<p> -For a description of how to enable CheckJNI for Android apps, see -<a href="embedded-vm-control.html">Controlling the Embedded VM</a>. -It's currently enabled by default in the Android emulator and on -"engineering" device builds. - -</p><p> -JNI checks can be modified with the <code>-Xjniopts</code> command-line -flag. Currently supported values include: -</p> -<blockquote><dl> -<dt>forcecopy -<dd>When set, any function that can return a copy of the original data -(array of primitive values, UTF-16 chars) will always do so. The buffers -are over-allocated and surrounded with a guard pattern to help identify -code writing outside the buffer, and the contents are erased before the -storage is freed to trip up code that uses the data after calling Release. -This will have a noticeable performance impact on some applications. -<dt>warnonly -<dd>By default, JNI "warnings" cause the VM to abort. With this flag -it continues on. -</dl></blockquote> - - -</p><p> -</p><h2><a name="Native_Libraries"> Native Libraries </a></h2> -<p> -You can load native code from shared libraries with the standard -<code>System.loadLibrary()</code> call. The -preferred way to get at your native code is: -</p><p> -</p><ul> -<li> Call <code>System.loadLibrary()</code> from a static class -initializer. (See the earlier example, where one is used to call -<code>nativeClassInit()</code>.) The argument is the "undecorated" -library name, e.g. to load "libfubar.so" you would pass in "fubar". - -</li> -<li> Provide a native function: <code><strong>jint JNI_OnLoad(JavaVM* vm, void* reserved)</strong></code> -</li> -<li>In <code>JNI_OnLoad</code>, register all of your native methods. You -should declare -the methods "static" so the names don't take up space in the symbol table -on the device. -</li> -</ul> -<p> -The <code>JNI_OnLoad</code> function should look something like this if -written in C: -</p><blockquote><pre>jint JNI_OnLoad(JavaVM* vm, void* reserved) -{ - JNIEnv* env; - if ((*vm)->GetEnv(vm, (void**) &env, JNI_VERSION_1_6) != JNI_OK) - return -1; - - /* get class with (*env)->FindClass */ - /* register methods with (*env)->RegisterNatives */ - - return JNI_VERSION_1_6; -} -</pre></blockquote> -</p><p> -You can also call <code>System.load()</code> with the full path name of the -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. -</p><p> -This is the recommended approach, but not the only approach. The VM does -not require explicit registration, nor that you provide a -<code>JNI_OnLoad</code> function. -You can instead use "discovery" of native methods that are named in a -specific way (see <a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp615"> - the JNI spec</a> for details), though this is less desirable. -It requires more space in the shared object symbol table, -loading is slower because it requires string searches through all of the -loaded shared libraries, and if a method signature is wrong you won't know -about it until the first time the method is actually used. -</p><p> -One other note about <code>JNI_OnLoad</code>: any <code>FindClass</code> -calls you make from there will happen in the context of the class loader -that was used to load the shared library. Normally <code>FindClass</code> -uses the loader associated with the method at the top of the interpreted -stack, or if there isn't one (because the thread was just attached to -the VM) it uses the "system" class loader. This makes -<code>JNI_OnLoad</code> a convenient place to look up and cache class -object references. -</p><p> - - -</p><h2><a name="64bit"> 64-bit Considerations </a></h2> - -<p> -Android is currently expected to run on 32-bit platforms. In theory it -could be built for a 64-bit system, but that is not a goal at this time. -For the most part this isn't something that you will need to worry about -when interacting with native code, -but it becomes significant if you plan to store pointers to native -structures in integer fields in an object. To support architectures -that use 64-bit pointers, <strong>you need to stash your native pointers in a -<code>long</code> field rather than an <code>int</code></strong>. - - -</p><h2><a name="Unsupported"> Unsupported Features </a></h2> -<p>All JNI 1.6 features are supported, with the following exceptions: -<ul> - <li><code>DefineClass</code> is not implemented. Dalvik does not use - Java bytecodes or class files, so passing in binary class data - doesn't work. Translation facilities may be added in a future - version of the VM.</li> - <li>"Weak global" references are implemented, but may only be passed - to <code>NewLocalRef</code>, <code>NewGlobalRef</code>, and - <code>DeleteWeakGlobalRef</code>. (The spec strongly encourages - programmers to create hard references to weak globals before doing - anything with them, so this should not be at all limiting.)</li> - <li><code>GetObjectRefType</code> (new in 1.6) is implemented but not fully - functional — it can't always tell the difference between "local" and - "global" references.</li> -</ul> - -<p>For backward compatibility, you may need to be aware of: -<ul> - <li>Until 2.0 ("Eclair"), the '$' character was not properly - converted to "_00024" during searches for method names. Working - around this requires using explicit registration or moving the - native methods out of inner classes. - <li>Until 2.0, it was not possible to use a <code>pthread_key_create</code> - destructor function to avoid the VM's "thread must be detached before - exit" check. (The VM also uses a pthread key destructor function, - so it'd be a race to see which gets called first.) - <li>"Weak global" references were not implemented until 2.2 ("Froyo"). - Older VMs will vigorously reject attempts to use them. You can use - the Android platform version constants to test for support. -</ul> - - -</p><h2><a name="FAQUnsatisfied"> FAQ: UnsatisfiedLinkError </a></h2> -<p> -When working on native code it's not uncommon to see a failure like this: -<pre>java.lang.UnsatisfiedLinkError: Library foo not found</pre> -<p> -In some cases it means what it says — the library wasn't found. In -other cases the library exists but couldn't be opened by dlopen(), and -the details of the failure can be found in the exception's detail message. -<p> -Common reasons why you might encounter "library not found" exceptions: -<ul> - <li>The library doesn't exist or isn't accessible to the app. Use - <code>adb shell ls -l <path></code> to check its presence - and permissions. - <li>The library wasn't built with the NDK. This can result in - dependencies on functions or libraries that don't exist on the device. -</ul> -</p><p> -Another class of <code>UnsatisfiedLinkError</code> failures looks like: -<pre>java.lang.UnsatisfiedLinkError: myfunc - at Foo.myfunc(Native Method) - at Foo.main(Foo.java:10)</pre> -<p> -In logcat, you'll see: -<pre>W/dalvikvm( 880): No implementation found for native LFoo;.myfunc ()V</pre> -<p> -This means that the VM tried to find a matching method but was unsuccessful. -Some common reasons for this are: -<ul> - <li>The library isn't getting loaded. Check the logcat output for - messages about library loading. - <li>The method isn't being found due to a name or signature mismatch. This - is commonly caused by: - <ul> - <li>For lazy method lookup, failing to declare C++ functions - with <code>extern C</code>. You can use <code>arm-eabi-nm</code> - to see the symbols as they appear in the library; if they look - mangled (e.g. <code>_Z15Java_Foo_myfuncP7_JNIEnvP7_jclass</code> - rather than <code>Java_Foo_myfunc</code>) then you need to - adjust the declaration. - <li>For explicit registration, minor errors when entering the - method signature. Make sure that what you're passing to the - registration call matches the signature in the log file. - Remember that 'B' is <code>byte</code> and 'Z' is <code>boolean</code>. - Class name components in signatures start with 'L', end with ';', - use '/' to separate package/class names, and use '$' to separate - inner-class names - (e.g. <code>Ljava/util/Map$Entry;</code>). - </ul> -</ul> -<p> -Using <code>javah</code> to automatically generate JNI headers may help -avoid some problems. - - -</p><h2><a name="FAQFindClass"> FAQ: FindClass didn't find my class </a></h2> -<p> -Make sure that the class name string has the correct format. JNI class -names start with the package name and are separated with slashes, -e.g. <code>java/lang/String</code>. If you're looking up an array class, -you need to start with the appropriate number of square brackets and -must also wrap the class with 'L' and ';', so a one-dimensional array of -<code>String</code> would be <code>[Ljava/lang/String;</code>. -</p><p> -If the class name looks right, you could be running into a class loader -issue. <code>FindClass</code> wants to start the class search in the -class loader associated with your code. It examines the VM call stack, -which will look something like: -<pre> Foo.myfunc(Native Method) - Foo.main(Foo.java:10) - dalvik.system.NativeStart.main(Native Method)</pre> -<p> -The topmost method is <code>Foo.myfunc</code>. <code>FindClass</code> -finds the <code>ClassLoader</code> object associated with the <code>Foo</code> -class and uses that. -</p><p> -This usually does what you want. You can get into trouble if you -create a thread outside the VM (perhaps by calling <code>pthread_create</code> -and then attaching it to the VM with <code>AttachCurrentThread</code>). -Now the stack trace looks like this: -<pre> dalvik.system.NativeStart.run(Native Method)</pre> -<p> -The topmost method is <code>NativeStart.run</code>, which isn't part of -your application. If you call <code>FindClass</code> from this thread, the -VM will start in the "system" class loader instead of the one associated -with your application, so attempts to find app-specific classes will fail. -</p><p> -There are a few ways to work around this: -<ul> - <li>Do your <code>FindClass</code> lookups once, in - <code>JNI_OnLoad</code>, and cache the class references for later - use. Any <code>FindClass</code> calls made as part of executing - <code>JNI_OnLoad</code> will use the class loader associated with - the function that called <code>System.loadLibrary</code> (this is a - special rule, provided to make library initialization more convenient). - If your app code is loading the library, <code>FindClass</code> - will use the correct class loader. - <li>Pass an instance of the class into the functions that need - it, e.g. declare your native method to take a Class argument and - then pass <code>Foo.class</code> in. - <li>Cache a reference to the <code>ClassLoader</code> object somewhere - handy, and issue <code>loadClass</code> calls directly. This requires - some effort. -</ul> - -</p><p> - - -</p><h2><a name="FAQSharing"> FAQ: Sharing raw data with native code </a></h2> -<p> -You may find yourself in a situation where you need to access a large -buffer of raw data from code written in Java and C/C++. Common examples -include manipulation of bitmaps or sound samples. There are two -basic approaches. -</p><p> -You can store the data in a <code>byte[]</code>. This allows very fast -access from code written in Java. On the native side, however, you're -not guaranteed to be able to access the data without having to copy it. In -some implementations, <code>GetByteArrayElements</code> and -<code>GetPrimitiveArrayCritical</code> will return actual pointers to the -raw data in the managed heap, but in others it will allocate a buffer -on the native heap and copy the data over. -</p><p> -The alternative is to store the data in a direct byte buffer. These -can be created with <code>java.nio.ByteBuffer.allocateDirect</code>, or -the JNI <code>NewDirectByteBuffer</code> function. Unlike regular -byte buffers, the storage is not allocated on the managed heap, and can -always be accessed directly from native code (get the address -with <code>GetDirectBufferAddress</code>). Depending on how direct -byte buffer access is implemented in the VM, accessing the data from code -written in Java can be very slow. -</p><p> -The choice of which to use depends on two factors: -<ol> - <li>Will most of the data accesses happen from code written in Java - or in C/C++? - <li>If the data is eventually being passed to a system API, what form - must it be in? (For example, if the data is eventually passed to a - function that takes a byte[], doing processing in a direct - <code>ByteBuffer</code> might be unwise.) -</ol> -If there's no clear winner, use a direct byte buffer. Support for them -is built directly into JNI, and access to them from code written in -Java can be made faster with VM improvements. -</p> - -<address>Copyright © 2008 The Android Open Source Project</address> - - </body> -</html> |