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 "native" methods to speed up JNI transitions.
26  *
27  * <p>
28  * This has the side-effect of disabling all garbage collections while executing a fast native
29  * method. Use with extreme caution. Any long-running methods must not be marked with
30  * {@code @FastNative} (including usually-fast but generally unbounded methods)!</p>
31  *
32  * <p><b>Deadlock Warning:</b>As a rule of thumb, do not acquire any locks during a fast native
33  * call if they aren't also locally released [before returning to managed code].</p>
34  *
35  * <p>
36  * Say some code does:
37  *
38  * <code>
39  * fast_jni_call_to_grab_a_lock();
40  * does_some_java_work();
41  * fast_jni_call_to_release_a_lock();
42  * </code>
43  *
44  * <p>
45  * This code can lead to deadlocks. Say thread 1 just finishes
46  * {@code fast_jni_call_to_grab_a_lock()} and is in {@code does_some_java_work()}.
47  * GC kicks in and suspends thread 1. Thread 2 now is in {@code fast_jni_call_to_grab_a_lock()}
48  * but is blocked on grabbing the native lock since it's held by thread 1.
49  * Now thread suspension can't finish since thread 2 can't be suspended since it's doing
50  * FastNative JNI.
51  * </p>
52  *
53  * <p>
54  * Normal JNI doesn't have the issue since once it's in native code,
55  * it is considered suspended from java's point of view.
56  * FastNative JNI however doesn't do the state transition done by JNI.
57  * </p>
58  *
59  * <p>
60  * Note that even in FastNative methods you <b>are</b> allowed to
61  * allocate objects and make upcalls into Java code. A call from Java to
62  * a FastNative function and back to Java is equivalent to a call from one Java
63  * method to another. What's forbidden in a FastNative method is blocking
64  * the calling thread in some non-Java code and thereby preventing the thread
65  * from responding to requests from the garbage collector to enter the suspended
66  * state.
67  * </p>
68  *
69  * <p>
70  * Has no effect when used with non-native methods.
71  * </p>
72  *
73  * @hide
74  */
75 @libcore.api.CorePlatformApi
76 @libcore.api.IntraCoreApi
77 @Retention(RetentionPolicy.CLASS)  // Save memory, don't instantiate as an object at runtime.
78 @Target(ElementType.METHOD)
79 public @interface FastNative {}
80