1 /* 2 * Copyright (C) 2017 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 non-static fields (instance variables) that act as handles to data that is 26 * explicitly cleaned up in response to the containing object becoming unreachable. Such cleanup 27 * is triggered by the garbage collector, typically by enqueuing a java.lang.ref.Reference, or by 28 * invoking an overridden finalize() method. The annotation is needed only when such explicit 29 * GC-triggered cleanup mechanisms are used. 30 * 31 * Most commonly, the fields f annotated this way will have primitive long type, but actually hold 32 * native pointers, as in: <pre> {@code 33 * 34 * {@literal @}ReachabilitySensitive 35 * private long nativePtr; // C++ pointer to NativeFoo. 36 * }</pre> 37 * 38 * Less frequently, such fields may also be e.g. Java references to Java objects that in turn 39 * contain such native pointers. Or they may be e.g. Java ints that are used to access Java data 40 * external to the object containing f. 41 * 42 * Specifically, an access inside a (static or instance) method of class C to a non-static 43 * field f of C declared ReachabilitySensitive behaves as though it results in the introduction of 44 * java.lang.ref.Reference.reachabilityFence()s according to the following rules: 45 * 46 * 1) For every local reference variable v declared immediately inside lexical scope s, if s 47 * contains such an access a, such that the field f accessed by a is reachable from v, then 48 * Reference.reachabilityFence(v) will be executed just before either (1) the exit of the scope s, 49 * or (2) just before any assignment to v. For our purposes, “this” is treated as a variable 50 * declared at method scope, as if it were an explicit parameter. 51 * 52 * 2) Define the full-expression containing e to be the largest enclosing expression f containing 53 * e, such that there is no statement both containing e and properly contained in f. If the 54 * full-expression containing the allocation of the object containing the field f is the same 55 * full-expression as the full-expression containing the access a, then 56 * Reference.reachabilityFence(p), where p is a reference to the object containing f, is executed 57 * at the end of the full expression. 58 * 59 * Some tools may implement these semantics by simply refusing to eliminate any dead references 60 * in a method accessing an @ReachabilitySensitive field of the same class. 61 * 62 * If the annotation is applied to an instance method, calls to that method are treated 63 * as accesses to a ReachabilitySensitive field of that object. Classes will normally 64 * not provide getter methods for ReachabilitySensitive fields, since that introduces a 65 * subtle dependency between the useful lifetime of the return value and the reachability 66 * of the original object. However if this cannot be avoided, such a getter method should 67 * be annotated as @ReachabilitySensitive. 68 * 69 * The annotation directly affects only methods of the containing class. There are situations in 70 * which accesses from another class (or calls from another class to an annotated method) are 71 * unavoidable. Normally all such accesses should be accompanied by corresponding 72 * reachabilityFence() calls. The @ReachabilitySensitive annotation allows tools to check that 73 * this is done. 74 * 75 * Note that the annotation also does not affect subclass methods. That is commonly OK. For 76 * example, native pointers should normally be declared private, and thus will only be accessed 77 * by methods of the same class. If an access from a subclass is unavoidable, again the 78 * annotation may allow tools to check for the required reachabilityFences. 79 * 80 * @hide 81 */ 82 @libcore.api.IntraCoreApi 83 @Retention(RetentionPolicy.RUNTIME) // Let the GC or interpreter ask, if they need to. 84 // TODO(b/72332040): Reconsider retention later. 85 @Target({ElementType.FIELD, ElementType.METHOD}) 86 public @interface ReachabilitySensitive {} 87