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 static android.annotation.SystemApi.Client.MODULE_LIBRARIES; 20 21 import android.annotation.SystemApi; 22 23 import java.lang.annotation.ElementType; 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 import java.lang.annotation.Target; 27 28 /** 29 * Applied to native methods to enable an ART runtime built-in optimization: 30 * methods that are annotated this way can speed up JNI transitions for methods that contain no 31 * objects (in parameters or return values, or as an implicit {@code this}). 32 * 33 * <p> 34 * The native implementation must exclude the {@code JNIEnv} and {@code jclass} parameters from its 35 * function signature. As an additional limitation, the method must be explicitly registered with 36 * {@code RegisterNatives} instead of relying on the built-in dynamic JNI linking. 37 * </p> 38 * 39 * <p> 40 * Performance of JNI transitions: 41 * <ul> 42 * <li>Regular JNI cost in nanoseconds: 115 43 * <li>Fast {@code (!)} JNI cost in nanoseconds: 60 44 * <li>{@literal @}{@link FastNative} cost in nanoseconds: 35 45 * <li>{@literal @}{@code CriticalNative} cost in nanoseconds: 25 46 * </ul> 47 * (Measured on angler-userdebug in 07/2016). 48 * </p> 49 * 50 * <p> 51 * A similar annotation, {@literal @}{@link FastNative}, exists with similar performance guarantees. 52 * However, unlike {@code @CriticalNative} it supports non-statics, object return values, and object 53 * parameters. If a method absolutely must have access to a {@code jobject}, then use 54 * {@literal @}{@link FastNative} instead of this. 55 * </p> 56 * 57 * <p> 58 * This has the side-effect of disabling all garbage collections while executing a critical native 59 * method. Use with extreme caution. Any long-running methods must not be marked with 60 * {@code @CriticalNative} (including usually-fast but generally unbounded methods)! 61 * </p> 62 * 63 * <p> 64 * <b>Deadlock Warning:</b> As a rule of thumb, do not acquire any locks during a critical native 65 * call if they aren't also locally released [before returning to managed code]. 66 * </p> 67 * 68 * <p> 69 * Say some code does: 70 * 71 * <code> 72 * critical_native_call_to_grab_a_lock(); 73 * does_some_java_work(); 74 * critical_native_call_to_release_a_lock(); 75 * </code> 76 * 77 * <p> 78 * This code can lead to deadlocks. Say thread 1 just finishes 79 * {@code critical_native_call_to_grab_a_lock()} and is in {@code does_some_java_work()}. 80 * GC kicks in and suspends thread 1. Thread 2 now is in 81 * {@code critical_native_call_to_grab_a_lock()} but is blocked on grabbing the 82 * native lock since it's held by thread 1. Now thread suspension can't finish 83 * since thread 2 can't be suspended since it's doing CriticalNative JNI. 84 * </p> 85 * 86 * <p> 87 * Normal natives don't have the issue since once it's executing in native code, 88 * it is considered suspended from the runtime's point of view. 89 * CriticalNative natives however don't do the state transition done by the normal natives. 90 * </p> 91 * 92 * <p> 93 * This annotation has no effect when used with non-native methods. 94 * The runtime must throw a {@code VerifierError} upon class loading if this is used with a native 95 * method that contains object parameters, an object return value, or a non-static. 96 * </p> 97 * 98 * @hide 99 */ 100 @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE) 101 @SystemApi(client = MODULE_LIBRARIES) 102 @Retention(RetentionPolicy.CLASS) // Save memory, don't instantiate as an object at runtime. 103 @Target(ElementType.METHOD) 104 public @interface CriticalNative {} 105