1 /*
2 * Copyright (c) 2018, 2025, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 *
23 */
24
25 #ifndef SHARE_OOPS_ACCESSDECORATORS_HPP
26 #define SHARE_OOPS_ACCESSDECORATORS_HPP
27
28 #include "cppstdlib/type_traits.hpp"
29 #include "gc/shared/barrierSetConfig.hpp"
30 #include "memory/allStatic.hpp"
31 #include "utilities/globalDefinitions.hpp"
32
33 // A decorator is an attribute or property that affects the way a memory access is performed in some way.
34 // There are different groups of decorators. Some have to do with memory ordering, others to do with,
35 // e.g. strength of references, strength of GC barriers, or whether compression should be applied or not.
36 // Some decorators are set at buildtime, such as whether primitives require GC barriers or not, others
37 // at callsites such as whether an access is in the heap or not, and others are resolved at runtime
38 // such as GC-specific barriers and encoding/decoding compressed oops.
39 typedef uint64_t DecoratorSet;
40
41 // The HasDecorator trait can help at compile-time determining whether a decorator set
42 // has an intersection with a certain other decorator set
43 template <DecoratorSet decorators, DecoratorSet decorator>
44 struct HasDecorator: public std::integral_constant<bool, (decorators & decorator) != 0> {};
45
46 // == General Decorators ==
47 // * DECORATORS_NONE: This is the name for the empty decorator set (in absence of other decorators).
48 const DecoratorSet DECORATORS_NONE = UCONST64(0);
49
50 // == Internal Decorators - do not use ==
51 // * INTERNAL_CONVERT_COMPRESSED_OOPS: This is an oop access that will require converting an oop
52 // to a narrowOop or vice versa, if UseCompressedOops is known to be set.
53 // * INTERNAL_VALUE_IS_OOP: Remember that the involved access is on oop rather than primitive.
54 const DecoratorSet INTERNAL_CONVERT_COMPRESSED_OOP = UCONST64(1) << 1;
55 const DecoratorSet INTERNAL_VALUE_IS_OOP = UCONST64(1) << 2;
56
57 // == Internal run-time Decorators ==
58 // * INTERNAL_RT_USE_COMPRESSED_OOPS: This decorator will be set in runtime resolved
59 // access backends iff UseCompressedOops is true.
60 const DecoratorSet INTERNAL_RT_USE_COMPRESSED_OOPS = UCONST64(1) << 5;
61
62 const DecoratorSet INTERNAL_DECORATOR_MASK = INTERNAL_CONVERT_COMPRESSED_OOP | INTERNAL_VALUE_IS_OOP |
63 INTERNAL_RT_USE_COMPRESSED_OOPS;
64
65 // == Memory Ordering Decorators ==
66 // The memory ordering decorators can be described in the following way:
67 // === Decorator Rules ===
68 // The different types of memory ordering guarantees have a strict order of strength.
69 // Explicitly specifying the stronger ordering implies that the guarantees of the weaker
70 // property holds too. The names come from the C++11 atomic operations, and typically
71 // have a JMM equivalent property.
72 // The equivalence may be viewed like this:
73 // MO_UNORDERED is equivalent to JMM plain.
74 // MO_RELAXED is equivalent to JMM opaque.
75 // MO_ACQUIRE is equivalent to JMM acquire.
76 // MO_RELEASE is equivalent to JMM release.
77 // MO_SEQ_CST is equivalent to JMM volatile.
78 //
79 // === Stores ===
80 // * MO_UNORDERED (Default): No guarantees.
81 // - The compiler and hardware are free to reorder aggressively. And they will.
82 // * MO_RELAXED: Relaxed atomic stores.
83 // - The stores are atomic.
84 // - The stores are not reordered by the compiler (but possibly the HW) w.r.t
85 // other ordered accesses in program order.
86 // - Also used for C++ volatile stores, since actual usage of volatile
87 // requires no word tearing.
88 // * MO_RELEASE: Releasing stores.
89 // - The releasing store will make its preceding memory accesses observable to memory accesses
90 // subsequent to an acquiring load observing this releasing store.
91 // - Guarantees from relaxed stores hold.
92 // * MO_SEQ_CST: Sequentially consistent stores.
93 // - The stores are observed in the same order by MO_SEQ_CST loads on other processors
94 // - Preceding loads and stores in program order are not reordered with subsequent loads and stores in program order.
95 // - Guarantees from releasing stores hold.
96 // === Loads ===
97 // * MO_UNORDERED (Default): No guarantees
98 // - The compiler and hardware are free to reorder aggressively. And they will.
99 // * MO_RELAXED: Relaxed atomic loads.
100 // - The loads are atomic.
101 // - The loads are not reordered by the compiler (but possibly the HW) w.r.t.
102 // other ordered accesses in program order.
103 // - Also used for C++ volatile loads, since actual usage of volatile
104 // requires no word tearing.
105 // * MO_ACQUIRE: Acquiring loads.
106 // - An acquiring load will make subsequent memory accesses observe the memory accesses
107 // preceding the releasing store that the acquiring load observed.
108 // - Guarantees from relaxed loads hold.
109 // * MO_SEQ_CST: Sequentially consistent loads.
110 // - These loads observe MO_SEQ_CST stores in the same order on other processors
111 // - Preceding MO_SEQ_CST loads and stores in program order are not reordered with
112 // subsequent MO_SEQ_CST loads and stores in program order.
113 // - Guarantees from acquiring loads hold.
114 // === Atomic Cmpxchg ===
115 // * MO_RELAXED: Atomic but relaxed cmpxchg.
116 // - Guarantees from MO_RELAXED loads and MO_RELAXED stores hold unconditionally.
117 // * MO_SEQ_CST: Sequentially consistent cmpxchg.
118 // - Guarantees from MO_SEQ_CST loads and MO_SEQ_CST stores hold unconditionally.
119 // === Atomic Xchg ===
120 // * MO_RELAXED: Atomic but relaxed atomic xchg.
121 // - Guarantees from MO_RELAXED loads and MO_RELAXED stores hold.
122 // * MO_SEQ_CST: Sequentially consistent xchg.
123 // - Guarantees from MO_SEQ_CST loads and MO_SEQ_CST stores hold.
124 const DecoratorSet MO_UNORDERED = UCONST64(1) << 6;
125 const DecoratorSet MO_RELAXED = UCONST64(1) << 7;
126 const DecoratorSet MO_ACQUIRE = UCONST64(1) << 8;
127 const DecoratorSet MO_RELEASE = UCONST64(1) << 9;
128 const DecoratorSet MO_SEQ_CST = UCONST64(1) << 10;
129 const DecoratorSet MO_DECORATOR_MASK = MO_UNORDERED | MO_RELAXED |
130 MO_ACQUIRE | MO_RELEASE | MO_SEQ_CST;
131
132 // === Barrier Strength Decorators ===
133 // * AS_RAW: The access will translate into a raw memory access, hence ignoring all semantic concerns
134 // except memory ordering and compressed oops. This will bypass runtime function pointer dispatching
135 // in the pipeline and hardwire to raw accesses without going through the GC access barriers.
136 // - Accesses on oop* translate to raw memory accesses without runtime checks
137 // - Accesses on narrowOop* translate to encoded/decoded memory accesses without runtime checks
138 // - Accesses on HeapWord* translate to a runtime check choosing one of the above
139 // - Accesses on other types translate to raw memory accesses without runtime checks
140 // * AS_NO_KEEPALIVE: The barrier is used only on oop references and will not keep any involved objects
141 // alive, regardless of the type of reference being accessed. This should be used with extreme caution
142 // in isolated scopes.
143 // AS_NO_KEEPALIVE stores are currently used primarily by the VM implementation of java.lang.ref.Reference
144 // and reference processing. AS_NO_KEEPALIVE loads have broader use, e.g. VM / serviceability introspection,
145 // printing, liveness checks, and weak (hash) table lookups.
146 // AS_NO_KEEPALIVE does not establish liveness for the current GC cycle. The oop returned by such
147 // a load, and any oop reached only by traversing from it, must not be stored as a new oop edge into
148 // GC-visible state (GC roots and the object graph). For SATB marking, violating this rule breaks
149 // the snapshot invariant. This includes, but is not limited to:
150 // - object graph storage (e.g. static and non-static Object fields, Object array elements)
151 // - local root storage (e.g. Handles, OopMap/GC-tracked frame / register slots)
152 // - other root storage (e.g. OopHandles, WeakHandles, nmethod and class metadata)
153 // Before such an oop is stored into GC-visible state, liveness must first be explicitly re-established,
154 // for example by:
155 // - re-resolving without AS_NO_KEEPALIVE
156 // - using CollectedHeap::keep_alive(oop)
157 // Related special case: for CLD-owned OopHandles (notably java mirrors), loading the oop does not
158 // keep the owning CLD / Klass alive. In those cases, a plain resolve() is insufficient; use the corresponding
159 // owner keep-alive helper (e.g. Klass::keep_alive()) or CollectedHeap::keep_alive(oop), or have some
160 // other guarantee of liveness before storing the oop into GC-visible state.
161 // * AS_NORMAL: The accesses will be resolved to an accessor on the BarrierSet class, giving the
162 // responsibility of performing the access and what barriers to be performed to the GC. This is the default.
163 // Note that primitive accesses will only be resolved on the barrier set if the appropriate build-time
164 // decorator for enabling primitive barriers is enabled for the build.
165 const DecoratorSet AS_RAW = UCONST64(1) << 11;
166 const DecoratorSet AS_NO_KEEPALIVE = UCONST64(1) << 12;
167 const DecoratorSet AS_NORMAL = UCONST64(1) << 13;
168 const DecoratorSet AS_DECORATOR_MASK = AS_RAW | AS_NO_KEEPALIVE | AS_NORMAL;
169
170 // === Reference Strength Decorators ===
171 // These decorators only apply to accesses on oop-like types (oop/narrowOop).
172 // * ON_STRONG_OOP_REF: Memory access is performed on a strongly reachable reference.
173 // * ON_WEAK_OOP_REF: The memory access is performed on a weakly reachable reference.
174 // * ON_PHANTOM_OOP_REF: The memory access is performed on a phantomly reachable reference.
175 // This is the same ring of strength as jweak and weak oops in the VM.
176 // * ON_UNKNOWN_OOP_REF: The memory access is performed on a reference of unknown strength.
177 // This could for example come from the unsafe API.
178 // * Default (no explicit reference strength specified): ON_STRONG_OOP_REF
179 const DecoratorSet ON_STRONG_OOP_REF = UCONST64(1) << 14;
180 const DecoratorSet ON_WEAK_OOP_REF = UCONST64(1) << 15;
181 const DecoratorSet ON_PHANTOM_OOP_REF = UCONST64(1) << 16;
182 const DecoratorSet ON_UNKNOWN_OOP_REF = UCONST64(1) << 17;
183 const DecoratorSet ON_DECORATOR_MASK = ON_STRONG_OOP_REF | ON_WEAK_OOP_REF |
184 ON_PHANTOM_OOP_REF | ON_UNKNOWN_OOP_REF;
185
186 // === Access Location ===
187 // Accesses can take place in, e.g. the heap, old or young generation, different native roots, or native memory off the heap.
188 // The location is important to the GC as it may imply different actions. The following decorators are used:
189 // * IN_HEAP: The access is performed in the heap. Many barriers such as card marking will
190 // be omitted if this decorator is not set.
191 // * IN_NATIVE: The access is performed in an off-heap data structure.
192 const DecoratorSet IN_HEAP = UCONST64(1) << 18;
193 const DecoratorSet IN_NATIVE = UCONST64(1) << 19;
194 const DecoratorSet IN_DECORATOR_MASK = IN_HEAP | IN_NATIVE;
195
196 // == Boolean Flag Decorators ==
197 // * IS_ARRAY: The access is performed on a heap allocated array. This is sometimes a special case
198 // for some GCs.
199 // * IS_DEST_UNINITIALIZED: This property can be important to e.g. SATB barriers by
200 // marking that the previous value is uninitialized nonsense rather than a real value.
201 // * IS_NOT_NULL: This property can make certain barriers faster such as compressing oops.
202 const DecoratorSet IS_ARRAY = UCONST64(1) << 20;
203 const DecoratorSet IS_DEST_UNINITIALIZED = UCONST64(1) << 21;
204 const DecoratorSet IS_NOT_NULL = UCONST64(1) << 22;
205
206 // == Arraycopy Decorators ==
207 // * ARRAYCOPY_CHECKCAST: This property means that the class of the objects in source
208 // are not guaranteed to be subclasses of the class of the destination array. This requires
209 // a check-cast barrier during the copying operation. If this is not set, it is assumed
210 // that the array is covariant: (the source array type is-a destination array type)
211 // * ARRAYCOPY_NOTNULL: This property means that the source array may contain null elements212 // but the destination does not allow null elements (i.e. throw NPE)
213 // * ARRAYCOPY_DISJOINT: This property means that it is known that the two array ranges
214 // are disjoint.
215 // * ARRAYCOPY_ARRAYOF: The copy is in the arrayof form.
216 // * ARRAYCOPY_ATOMIC: The accesses have to be atomic over the size of its elements.
217 // * ARRAYCOPY_ALIGNED: The accesses have to be aligned on a HeapWord.
218 const DecoratorSet ARRAYCOPY_CHECKCAST = UCONST64(1) << 23;
219 const DecoratorSet ARRAYCOPY_NOTNULL = UCONST64(1) << 24;220 const DecoratorSet ARRAYCOPY_DISJOINT = UCONST64(1) << 25;221 const DecoratorSet ARRAYCOPY_ARRAYOF = UCONST64(1) << 26;222 const DecoratorSet ARRAYCOPY_ATOMIC = UCONST64(1) << 27;223 const DecoratorSet ARRAYCOPY_ALIGNED = UCONST64(1) << 28;224 const DecoratorSet ARRAYCOPY_DECORATOR_MASK = ARRAYCOPY_CHECKCAST | ARRAYCOPY_NOTNULL |
225 ARRAYCOPY_DISJOINT | ARRAYCOPY_ARRAYOF |
226 ARRAYCOPY_ATOMIC | ARRAYCOPY_ALIGNED;
227
228 // == Resolve barrier decorators ==
229 // * ACCESS_READ: Indicate that the resolved object is accessed read-only. This allows the GC
230 // backend to use weaker and more efficient barriers.
231 // * ACCESS_WRITE: Indicate that the resolved object is used for write access.
232 const DecoratorSet ACCESS_READ = UCONST64(1) << 29;233 const DecoratorSet ACCESS_WRITE = UCONST64(1) << 30;
234
235 // Keep track of the last decorator.
236 const DecoratorSet DECORATOR_LAST = UCONST64(1) << 30;
237
238 namespace AccessInternal {
239 // This class adds implied decorators that follow according to decorator rules.
240 // For example adding default reference strength and default memory ordering
241 // semantics.
242 template <DecoratorSet input_decorators>
243 struct DecoratorFixup: AllStatic {
244 // If no reference strength has been picked, then strong will be picked
245 static const DecoratorSet ref_strength_default = input_decorators |
246 (((ON_DECORATOR_MASK & input_decorators) == 0 && (INTERNAL_VALUE_IS_OOP & input_decorators) != 0) ?
247 ON_STRONG_OOP_REF : DECORATORS_NONE);
248 // If no memory ordering has been picked, unordered will be picked
249 static const DecoratorSet memory_ordering_default = ref_strength_default |
250 ((MO_DECORATOR_MASK & ref_strength_default) == 0 ? MO_UNORDERED : DECORATORS_NONE);
251 // If no barrier strength has been picked, normal will be used
252 static const DecoratorSet barrier_strength_default = memory_ordering_default |
253 ((AS_DECORATOR_MASK & memory_ordering_default) == 0 ? AS_NORMAL : DECORATORS_NONE);
254 static const DecoratorSet value = barrier_strength_default;
255 };
256
257 // This function implements the above DecoratorFixup rules, but without meta
258 // programming for code generation that does not use templates.
259 inline DecoratorSet decorator_fixup(DecoratorSet input_decorators, BasicType type) {
260 // Some call-sites don't specify that the access is performed on oops
261 DecoratorSet with_oop_decorators = input_decorators |= (is_reference_type(type) ? INTERNAL_VALUE_IS_OOP : 0);
262 // If no reference strength has been picked, then strong will be picked
263 DecoratorSet ref_strength_default = with_oop_decorators |
264 (((ON_DECORATOR_MASK & with_oop_decorators) == 0 && (INTERNAL_VALUE_IS_OOP & input_decorators) != 0) ?
265 ON_STRONG_OOP_REF : DECORATORS_NONE);
266 // If no memory ordering has been picked, unordered will be picked
267 DecoratorSet memory_ordering_default = ref_strength_default |
268 ((MO_DECORATOR_MASK & ref_strength_default) == 0 ? MO_UNORDERED : DECORATORS_NONE);
269 // If no barrier strength has been picked, normal will be used
270 DecoratorSet barrier_strength_default = memory_ordering_default |
271 ((AS_DECORATOR_MASK & memory_ordering_default) == 0 ? AS_NORMAL : DECORATORS_NONE);
272 return barrier_strength_default;
273 }
274 }
275
276 #endif // SHARE_OOPS_ACCESSDECORATORS_HPP
--- EOF ---