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