1 /* 2 * Copyright (C) 2014 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 #ifndef ART_RUNTIME_READ_BARRIER_OPTION_H_ 18 #define ART_RUNTIME_READ_BARRIER_OPTION_H_ 19 20 #include "base/macros.h" 21 22 namespace art HIDDEN { 23 24 // Options for performing a read barrier or not. 25 // 26 // Besides disabled GC and GC's internal usage, there are a few cases where the read 27 // barrier is unnecessary and can be avoided to reduce code size and improve performance. 28 // In the following cases, the result of the operation or chain of operations shall be the 29 // same whether we go through the from-space or to-space: 30 // 31 // 1. We're reading a reference known to point to an un-reclaimable immune space object. 32 // (For example boot image class and string references, read by compiled code from 33 // .data.img.rel.ro . Similarly, such references constructed using position independent 34 // code in the compiled boot image code do not need a read barrier.) 35 // 2. We're reading the reference for comparison involving a non-moving space reference. 36 // (Whether the non-moving space reference is the one we're reading or the one we shall 37 // compare it with, the result is the same with and without read barrier.) 38 // 3. We're reading the reference for comparison with null. 39 // (Similar to 2 above, given that null is "non-moving".) 40 // 4. We're reading a reference to a holder from which we shall read 41 // - constant primitive field, or 42 // - mutable primitive field for testing an invariant, or 43 // - constant reference field known to point to an un-reclaimable immune space object, or 44 // - constant reference field for comparison involving a non-moving space reference, or 45 // - constant reference field for comparison with null, or 46 // - constant reference fields in a chain leading to one or more of the above purposes; 47 // the entire chain needs to be read without read barrier. 48 // The terms "constant" and "invariant" refer to values stored in holder fields before the 49 // holder reference is stored in the location for which we want to avoid the read barrier. 50 // Since the stored holder reference points to an object with the initialized constant or 51 // invariant, when we start a new GC and that holder instance becomes a from-space object 52 // both the from-space and to-space versions shall hold the same constant or invariant. 53 // 54 // While correct inter-thread memory visibility needs to be ensured for these constants and 55 // invariants, it needs to be equally ensured for non-moving GC types, so read barriers or 56 // their avoidance do not place any additional constraints on inter-thread synchronization. 57 // 58 // References read without a read barrier must not remain live at the next suspend point, 59 // with the exception of references to un-reclaimable immune space objects. 60 // 61 // For un-reclaimable immune space objects, we rely on graying dirty objects in the FlipCallback 62 // pause (we try to gray them just before flipping thread roots but the FlipCallback has to re-scan 63 // for newly dirtied objects) and clean objects conceptually become black at that point 64 // (marking them through is a no-op as all reference fields must also point to immune spaces), 65 // so mutator threads can never miss a read barrier as they never see white immune space object. 66 // 67 // Examples: 68 // 69 // The j.l.Class contains many constant fields and invariants: 70 // - primitive type is constant (primitive classes are pre-initialized in the boot image, 71 // or created in early single-threaded stage when running without boot image; non-primitive 72 // classes keep the value 0 from the Class object allocation), 73 // - element type is constant (initialized during array class object allocation, null otherwise), 74 // - access flags are mutable but the proxy class bit is an invariant set during class creation, 75 // - once the class is resolved, the class status is still mutable but it shall remain resolved, 76 // being a resolved is an invariant from that point on, 77 // - once a class becomes erroneous, the class status shall be constant (and unresolved 78 // erroneous class shall not become resolved). 79 // This allows reading a chain of element type references for any number of array dimensions 80 // without read barrier to find the (non-array) element class and check whether it's primitive, 81 // or proxy class. When creating an array class, the element type is already either resolved or 82 // unresolved erroneous and neither shall change, so we can also check these invariants (but not 83 // resolved erroneous because that is not an invariant from the creation of the array class). 84 // 85 // The superclass becomes constant during the ClassStatus::kIdx stage, so it's safe to treat it 86 // as constant when reading from locations that can reference only resolved classes. 87 enum EXPORT ReadBarrierOption { 88 kWithReadBarrier, // Perform a read barrier. 89 kWithoutReadBarrier, // Don't perform a read barrier. 90 kWithFromSpaceBarrier, // Get the from-space address for the given to-space address. Used by CMC 91 }; 92 93 } // namespace art 94 95 #endif // ART_RUNTIME_READ_BARRIER_OPTION_H_ 96