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