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