1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package dalvik.annotation.optimization; 18 19 import java.lang.annotation.ElementType; 20 import java.lang.annotation.Retention; 21 import java.lang.annotation.RetentionPolicy; 22 import java.lang.annotation.Target; 23 24 /** 25 * An ART runtime built-in optimization for {@code native} methods to speed up JNI transitions: 26 * Compared to normal {@code native} methods, {@code native} methods that are annotated with 27 * {@literal @}{@code FastNative} use faster JNI transitions from managed code to the native code 28 * and back. Calls from a {@literal @}{@code FastNative} method implementation to JNI functions 29 * that access the managed heap or call managed code also have faster internal transitions. 30 * 31 * <p> 32 * While executing a {@literal @}{@code FastNative} method, the garbage collection cannot 33 * suspend the thread for essential work and may become blocked. Use with caution. Do not use 34 * this annotation for long-running methods, including usually-fast, but generally unbounded, 35 * methods. In particular, the code should not perform significant I/O operations or acquire 36 * native locks that can be held for a long time. (Some logging or native allocations, which 37 * internally acquire native locks for a short time, are generally OK. However, as the cost 38 * of several such operations adds up, the {@literal @}{@code FastNative} performance gain 39 * can become insignificant and overshadowed by potential GC delays.) 40 * Acquiring managed locks is OK as it internally allows thread suspension. 41 * </p> 42 * 43 * <p> 44 * For performance critical methods that need this annotation, it is strongly recommended 45 * to explicitly register the method(s) with JNI {@code RegisterNatives} instead of relying 46 * on the built-in dynamic JNI linking. 47 * </p> 48 * 49 * <p> 50 * The {@literal @}{@code FastNative} optimization was implemented for system use since 51 * Android 8 and became CTS-tested public API in Android 14. Developers aiming for maximum 52 * compatibility should avoid calling {@literal @}{@code FastNative} methods on Android 13-. 53 * The optimization is likely to work also on Android 8-13 devices (after all, it was used 54 * in the system, albeit without the strong CTS guarantees), especially those that use 55 * unmodified versions of ART, such as Android 12+ devices with the official ART Module. 56 * The built-in dynamic JNI linking is working only in Android 12+, the explicit registration 57 * with JNI {@code RegisterNatives} is strictly required for running on Android versions 8-11. 58 * The annotation is ignored on Android 7-. 59 * </p> 60 * 61 * <p> 62 * <b>Deadlock Warning:</b> As a rule of thumb, any native locks acquired in a 63 * {@literal @}{@link FastNative} call (despite the above warning that this is an unbounded 64 * operation that can block GC for a long time) must be released before returning to managed code. 65 * </p> 66 * 67 * <p> 68 * Say some code does: 69 * 70 * <code> 71 * fast_jni_call_to_grab_a_lock(); 72 * does_some_java_work(); 73 * fast_jni_call_to_release_a_lock(); 74 * </code> 75 * 76 * <p> 77 * This code can lead to deadlocks. Say thread 1 just finishes 78 * {@code fast_jni_call_to_grab_a_lock()} and is in {@code does_some_java_work()}. 79 * GC kicks in and suspends thread 1. Thread 2 now is in {@code fast_jni_call_to_grab_a_lock()} 80 * but is blocked on grabbing the native lock since it's held by thread 1. 81 * Now thread suspension can't finish since thread 2 can't be suspended since it's doing 82 * FastNative JNI. 83 * </p> 84 * 85 * <p> 86 * Normal JNI doesn't have the issue since once it's in native code, 87 * it is considered suspended from java's point of view. 88 * FastNative JNI however doesn't do the state transition done by JNI. 89 * </p> 90 * 91 * <p> 92 * Note that even in FastNative methods you <b>are</b> allowed to 93 * allocate objects and make upcalls into Java code. A call from Java to 94 * a FastNative function and back to Java is equivalent to a call from one Java 95 * method to another. What's forbidden in a FastNative method is blocking 96 * the calling thread in some non-Java code and thereby preventing the thread 97 * from responding to requests from the garbage collector to enter the suspended 98 * state. 99 * </p> 100 * 101 * <p> 102 * Has no effect when used with non-native methods. 103 * </p> 104 */ 105 @Retention(RetentionPolicy.CLASS) // Save memory, don't instantiate as an object at runtime. 106 @Target(ElementType.METHOD) 107 public @interface FastNative {} 108