| /* |
| * Copyright (C) 2018 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package dalvik.annotation.optimization; |
| |
| import java.lang.annotation.ElementType; |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.lang.annotation.Target; |
| |
| /** |
| * Allow the implementation to eliminate object references that are no longer needed, just as it |
| * would eliminate other dead variables. |
| * |
| * The annotation applies to methods of the annotated class, and to methods declared in any inner |
| * class declared inside the annotated class. It does not apply to methods declared in subclasses |
| * or superclasses. It is ignored for interfaces. |
| * |
| * The annotation promises that the implementation of this class remains correct if objects are |
| * finalized, and java.lang.ref References are enqueued, as soon as the JLS allows them to be, |
| * i.e. after they are allowed to be marked as unreachable according to the JLS. Historically, the |
| * Android runtime has garbage collected objects later than the JLS would allow, by retaining |
| * objects references that are no longer needed. Some classes that implement finalize() or make |
| * use of java.lang.ref APIs may have grown to depend on this historic Android runtime behavior. |
| * |
| * For example, consider the method |
| * |
| * <pre> {@code |
| * void m() { |
| * long tmpNativePtr = this.nativePtrField; |
| * foo(tmpNativePtr); |
| * }}</pre> |
| * |
| * where foo() accesses the memory M referenced by {@code this.nativePtrField}. Once {@code |
| * tmpNativePtr} is computed, this object itself is no longer needed, and may be unreachable by JLS |
| * rules. This may cause this object to be finalized, and M to be deleted, while {@code foo()} is |
| * still running and accessing M. |
| * |
| * Historically, ART has avoided this by keeping "this" reachable until {@code m()} completes. |
| * (Class file and dex level tools may not always do the same.) With this annotation, the Android |
| * runtime may no longer retain the "this" reference, again making the erroneous early |
| * finalization possible. |
| * |
| * The above example code could be made safe to annotate with {@code DeadReferenceSafe} by either |
| * adding Reference.reachabilityFence(this) to the end of {@code m()} and similar methods, or |
| * (Android-only) by declaring nativePtrField with a {@code @ReachabilitySensitive} annotation. |
| * |
| * The annotation will normally be safe for classes that do not use or rely on finalization-like |
| * cleanup mechanisms. It is unlikely to be safe for classes that use {@code java.lang.ref} or |
| * finalization but never mention {@code reachabilityFence()} or {@code @ReachabilitySensitive}. |
| * |
| * When it is safe, this annotation might result in better performance because more memory can be |
| * reclaimed earlier by the garbage collector. |
| * |
| * Since this is technically safe for all classes that follow Java language rules, we expect this |
| * to eventually become the default. This annotation allows us to selectively enable dead |
| * reference elimination during the transition, and while the details of {@code |
| * @ReachabilitySensitive} (like its name) are in flux. |
| * |
| * @hide |
| */ |
| @Retention(RetentionPolicy.RUNTIME) // Let the GC or interpreter ask, if they need to. |
| @Target({ElementType.TYPE}) |
| public @interface DeadReferenceSafe {} |