The Android runtime (ART) is the default runtime for devices running Android 5.0 (API level 21) and higher. This runtime offers a number of features that improve performance and smoothness of the Android platform and apps. You can find more information about ART's new features in Introducing ART.
However, some techniques that work on Dalvik do not work on ART. This document lets you know about things to watch for when migrating an existing app to be compatible with ART. Most apps should just work when running with ART.
Under Dalvik, apps frequently find it useful to explicitly call
System.gc() to prompt garbage collection (GC). This should be
far less necessary with ART, particularly if you're invoking garbage collection
occurrences or to reduce fragmentation. You can verify which runtime is in use
System.getProperty("java.vm.version"). If ART is in use, the property's value
"2.0.0" or higher.
Furthermore, a compacting garbage collector is under development in the Android Open-Source Project (AOSP) to improve memory management. Because of this, you should avoid using techniques that are incompatible with compacting GC (such as saving pointers to object instance data). This is particularly important for apps that make use of the Java Native Interface (JNI). For more information, see Preventing JNI Issues.
ART's JNI is somewhat stricter than Dalvik's. It is an especially good idea to use CheckJNI mode to catch common problems. If your app makes use of C/C++ code, you should review the following article:
ART has a compacting garbage collector under development on the Android Open Source Project (AOSP). Once the compacting garbage collector is in use, objects may be moved in memory. If you use C/C++ code, do not perform operations that are incompatible with compacting GC. We have enhanced CheckJNI to identify some potential issues (as described in JNI Local Reference Changes in ICS).
One area to watch for in particular is the use of
functions. In runtimes with non-compacting GC, the
Get...ArrayElements() functions typically return a reference to the
actual memory backing the array object. If you make a change to one of the
returned array elements, the array object is itself changed (and the arguments
Release...ArrayElements() are usually ignored). However, if
compacting GC is in use, the
Get...ArrayElements() functions may
return a copy of the memory. If you misuse the reference when compacting GC is
in use, this can lead to memory corruption or other problems. For example:
Release...ArrayElements()function when you are done, to make sure the changes you made are correctly copied back to the underlying array object.
JNI_ABORTmode, which releases the memory without copying changes back to the underlying array object.
0(which updates the array object and frees the copy of the memory).
JNI_COMMIT(which updates the underlying array object and retains the copy).
Release...ArrayElements(), return the same pointer that was originally returned by
Get...ArrayElements(). For example, it's not safe to increment the original pointer (to scan through the returned array elements) then pass the incremented pointer to
Release...ArrayElements(). Passing this modified pointer can cause the wrong memory to be freed, resulting in memory corruption.
ART's JNI throws errors in a number of cases where Dalvik doesn’t. (Once again, you can catch many such cases by testing with CheckJNI.)
For example, if
RegisterNatives is called with a method that
does not exist (perhaps because the method was removed by a tool such as
ProGuard), ART now properly throws
08-12 17:09:41.082 13823 13823 E AndroidRuntime: FATAL EXCEPTION: main 08-12 17:09:41.082 13823 13823 E AndroidRuntime: java.lang.NoSuchMethodError: no static or non-static method "Lcom/foo/Bar;.native_frob(Ljava/lang/String;)I" 08-12 17:09:41.082 13823 13823 E AndroidRuntime: at java.lang.Runtime.nativeLoad(Native Method) 08-12 17:09:41.082 13823 13823 E AndroidRuntime: at java.lang.Runtime.doLoad(Runtime.java:421) 08-12 17:09:41.082 13823 13823 E AndroidRuntime: at java.lang.Runtime.loadLibrary(Runtime.java:362) 08-12 17:09:41.082 13823 13823 E AndroidRuntime: at java.lang.System.loadLibrary(System.java:526)
ART also logs an error (visible in logcat) if
called with no methods:
W/art ( 1234): JNI RegisterNativeMethods: attempt to register 0 native methods for <classname>
In addition, the JNI functions
GetStaticFieldID() now properly throw
instead of simply returning null. Similarly,
GetStaticMethodID() now properly throw
This can lead to CheckJNI failures because of the unhandled exceptions or the
exceptions being thrown to Java callers of native code. This makes it
particularly important to test ART-compatible apps with CheckJNI mode.
ART expects users of the JNI
CallNonvirtualVoidMethod()) to use the method's declaring
class, not a subclass, as required by the JNI specification.
Dalvik had separate stacks for native and Java code, with a default Java
stack size of 32KB and a default native stack size of 1MB. ART has a unified
stack for better locality. Ordinarily, the ART
size should be approximately the same as for Dalvik. However, if you explicitly
set stack sizes, you may need to revisit those values for apps running in
Threadconstructor that specify an explicit stack size. For example, you will need to increase the size if
pthread_attr_setstacksize()for threads that also run Java code via JNI. Here is an example of the error logged when an app attempts to call JNI
AttachCurrentThread()when the pthread size is too small:
F/art: art/runtime/thread.cc:435] Attempt to attach a thread with a too-small stack (16384 bytes)
Dalvik incorrectly allowed subclasses to override package-private methods. ART issues a warning in such cases:
Before Android 4.1, method void com.foo.Bar.quux() would have incorrectly overridden the package-private method in com.quux.Quux
If you intend to override a class's method in a different package, declare the
Object now has private fields. Apps that reflect on fields
in their class hierarchies should be careful not to attempt to look at the
Object. For example, if you are iterating up a class
hierarchy as part of a serialization framework, stop when
Class.getSuperclass() == java.lang.Object.classinstead of continuing until the method returns
InvocationHandler.invoke() now receives
null if there are no
arguments instead of an empty array. This behavior was documented previously but
not correctly handled in Dalvik. Previous versions of Mockito have difficulties with
this, so use an updated Mockito version when testing with ART.
ART's Ahead-Of-Time (AOT) Java compilation should work for all standard Java
code. Compilation is performed by ART's
dex2oat tool; if you encounter any issues related to
dex2oat at install time, let us know (see Reporting Problems) so we can fix them as quickly
as possible. A couple of issues to note:
.odexfile format in
/data/dalvik-cache, or in
DexClassLoader’s optimized output directory. These files are now ELF files and not an extended form of DEX files. While ART tries to follow the same naming and locking rules as Dalvik, apps should not depend on the file format; the format is subject to change without notice.
If you run into any issues that aren’t due to app JNI issues, report
them via the Android Open Source Project Issue Tracker at https://code.google.com/p/android/issues/list.
"adb bugreport" and a link to the app in the Google
Play store if available. Otherwise, if possible, attach an APK that reproduces
the issue. Note that issues (including attachments) are publicly