1 /* 2 * Copyright (c) 2017, 2023, 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_ACCESS_HPP 26 #define SHARE_OOPS_ACCESS_HPP 27 28 #include "memory/allStatic.hpp" 29 #include "oops/accessBackend.hpp" 30 #include "oops/accessDecorators.hpp" 31 #include "oops/oopsHierarchy.hpp" 32 #include "utilities/debug.hpp" 33 #include "utilities/globalDefinitions.hpp" 34 35 36 // = GENERAL = 37 // Access is an API for performing accesses with declarative semantics. Each access can have a number of "decorators". 38 // A decorator is an attribute or property that affects the way a memory access is performed in some way. 39 // There are different groups of decorators. Some have to do with memory ordering, others to do with, 40 // e.g. strength of references, strength of GC barriers, or whether compression should be applied or not. 41 // Some decorators are set at buildtime, such as whether primitives require GC barriers or not, others 42 // at callsites such as whether an access is in the heap or not, and others are resolved at runtime 43 // such as GC-specific barriers and encoding/decoding compressed oops. For more information about what 44 // decorators are available, cf. oops/accessDecorators.hpp. 45 // By pipelining handling of these decorators, the design of the Access API allows separation of concern 46 // over the different orthogonal concerns of decorators, while providing a powerful way of 47 // expressing these orthogonal semantic properties in a unified way. 48 // 49 // == OPERATIONS == 50 // * load: Load a value from an address. 51 // * load_at: Load a value from an internal pointer relative to a base object. 52 // * store: Store a value at an address. 53 // * store_at: Store a value in an internal pointer relative to a base object. 54 // * atomic_cmpxchg: Atomically compare-and-swap a new value at an address if previous value matched the compared value. 55 // * atomic_cmpxchg_at: Atomically compare-and-swap a new value at an internal pointer address if previous value matched the compared value. 56 // * atomic_xchg: Atomically swap a new value at an address if previous value matched the compared value. 57 // * atomic_xchg_at: Atomically swap a new value at an internal pointer address if previous value matched the compared value. 58 // * arraycopy: Copy data from one heap array to another heap array. The ArrayAccess class has convenience functions for this. 59 // * clone: Clone the contents of an object to a newly allocated object. 60 // 61 // == IMPLEMENTATION == 62 // Each access goes through the following steps in a template pipeline. 63 // There are essentially 5 steps for each access: 64 // * Step 1: Set default decorators and decay types. This step gets rid of CV qualifiers 65 // and sets default decorators to sensible values. 66 // * Step 2: Reduce types. This step makes sure there is only a single T type and not 67 // multiple types. The P type of the address and T type of the value must 68 // match. 69 // * Step 3: Pre-runtime dispatch. This step checks whether a runtime call can be 70 // avoided, and in that case avoids it (calling raw accesses or 71 // primitive accesses in a build that does not require primitive GC barriers) 72 // * Step 4: Runtime-dispatch. This step performs a runtime dispatch to the corresponding 73 // BarrierSet::AccessBarrier accessor that attaches GC-required barriers 74 // to the access. 75 // * Step 5.a: Barrier resolution. This step is invoked the first time a runtime-dispatch 76 // happens for an access. The appropriate BarrierSet::AccessBarrier accessor 77 // is resolved, then the function pointer is updated to that accessor for 78 // future invocations. 79 // * Step 5.b: Post-runtime dispatch. This step now casts previously unknown types such 80 // as the address type of an oop on the heap (is it oop* or narrowOop*) to 81 // the appropriate type. It also splits sufficiently orthogonal accesses into 82 // different functions, such as whether the access involves oops or primitives 83 // and whether the access is performed on the heap or outside. Then the 84 // appropriate BarrierSet::AccessBarrier is called to perform the access. 85 // 86 // The implementation of step 1-4 resides in in accessBackend.hpp, to allow selected 87 // accesses to be accessible from only access.hpp, as opposed to access.inline.hpp. 88 // Steps 5.a and 5.b require knowledge about the GC backends, and therefore needs to 89 // include the various GC backend .inline.hpp headers. Their implementation resides in 90 // access.inline.hpp. The accesses that are allowed through the access.hpp file 91 // must be instantiated in access.cpp using the INSTANTIATE_HPP_ACCESS macro. 92 93 template <DecoratorSet decorators = DECORATORS_NONE> 94 class Access: public AllStatic { 95 // This function asserts that if an access gets passed in a decorator outside 96 // of the expected_decorators, then something is wrong. It additionally checks 97 // the consistency of the decorators so that supposedly disjoint decorators are indeed 98 // disjoint. For example, an access can not be both in heap and on root at the 99 // same time. 100 template <DecoratorSet expected_decorators> 101 static void verify_decorators(); 102 103 template <DecoratorSet expected_mo_decorators> 104 static void verify_primitive_decorators() { 105 const DecoratorSet primitive_decorators = (AS_DECORATOR_MASK ^ AS_NO_KEEPALIVE) | 106 IN_HEAP | IS_ARRAY; 107 verify_decorators<expected_mo_decorators | primitive_decorators>(); 108 } 109 110 template <DecoratorSet expected_mo_decorators> 111 static void verify_oop_decorators() { 112 const DecoratorSet oop_decorators = AS_DECORATOR_MASK | IN_DECORATOR_MASK | 113 (ON_DECORATOR_MASK ^ ON_UNKNOWN_OOP_REF) | // no unknown oop refs outside of the heap 114 IS_ARRAY | IS_NOT_NULL | IS_DEST_UNINITIALIZED; 115 verify_decorators<expected_mo_decorators | oop_decorators>(); 116 } 117 118 template <DecoratorSet expected_mo_decorators> 119 static void verify_heap_oop_decorators() { 120 const DecoratorSet heap_oop_decorators = AS_DECORATOR_MASK | ON_DECORATOR_MASK | 121 IN_HEAP | IS_ARRAY | IS_NOT_NULL | IS_DEST_UNINITIALIZED; 122 verify_decorators<expected_mo_decorators | heap_oop_decorators>(); 123 } 124 125 static const DecoratorSet load_mo_decorators = MO_UNORDERED | MO_RELAXED | MO_ACQUIRE | MO_SEQ_CST; 126 static const DecoratorSet store_mo_decorators = MO_UNORDERED | MO_RELAXED | MO_RELEASE | MO_SEQ_CST; 127 static const DecoratorSet atomic_xchg_mo_decorators = MO_SEQ_CST; 128 static const DecoratorSet atomic_cmpxchg_mo_decorators = MO_RELAXED | MO_SEQ_CST; 129 130 protected: 131 template <typename T> 132 static inline bool oop_arraycopy(arrayOop src_obj, size_t src_offset_in_bytes, const T* src_raw, 133 arrayOop dst_obj, size_t dst_offset_in_bytes, T* dst_raw, 134 size_t length) { 135 verify_decorators<ARRAYCOPY_DECORATOR_MASK | IN_HEAP | 136 AS_DECORATOR_MASK | IS_ARRAY | IS_DEST_UNINITIALIZED>(); 137 return AccessInternal::arraycopy<decorators | INTERNAL_VALUE_IS_OOP>(src_obj, src_offset_in_bytes, src_raw, 138 dst_obj, dst_offset_in_bytes, dst_raw, 139 length); 140 } 141 142 template <typename T> 143 static inline void arraycopy(arrayOop src_obj, size_t src_offset_in_bytes, const T* src_raw, 144 arrayOop dst_obj, size_t dst_offset_in_bytes, T* dst_raw, 145 size_t length) { 146 verify_decorators<ARRAYCOPY_DECORATOR_MASK | IN_HEAP | 147 AS_DECORATOR_MASK | IS_ARRAY>(); 148 AccessInternal::arraycopy<decorators>(src_obj, src_offset_in_bytes, src_raw, 149 dst_obj, dst_offset_in_bytes, dst_raw, 150 length); 151 } 152 153 public: 154 // Primitive heap accesses 155 static inline AccessInternal::LoadAtProxy<decorators> load_at(oop base, ptrdiff_t offset) { 156 verify_primitive_decorators<load_mo_decorators>(); 157 return AccessInternal::LoadAtProxy<decorators>(base, offset); 158 } 159 160 template <typename T> 161 static inline void store_at(oop base, ptrdiff_t offset, T value) { 162 verify_primitive_decorators<store_mo_decorators>(); 163 AccessInternal::store_at<decorators>(base, offset, value); 164 } 165 166 template <typename T> 167 static inline T atomic_cmpxchg_at(oop base, ptrdiff_t offset, T compare_value, T new_value) { 168 verify_primitive_decorators<atomic_cmpxchg_mo_decorators>(); 169 return AccessInternal::atomic_cmpxchg_at<decorators>(base, offset, compare_value, new_value); 170 } 171 172 template <typename T> 173 static inline T atomic_xchg_at(oop base, ptrdiff_t offset, T new_value) { 174 verify_primitive_decorators<atomic_xchg_mo_decorators>(); 175 return AccessInternal::atomic_xchg_at<decorators>(base, offset, new_value); 176 } 177 178 // Oop heap accesses 179 static inline AccessInternal::OopLoadAtProxy<decorators> oop_load_at(oop base, ptrdiff_t offset) { 180 verify_heap_oop_decorators<load_mo_decorators>(); 181 return AccessInternal::OopLoadAtProxy<decorators>(base, offset); 182 } 183 184 template <typename T> 185 static inline void oop_store_at(oop base, ptrdiff_t offset, T value) { 186 verify_heap_oop_decorators<store_mo_decorators>(); 187 typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType; 188 OopType oop_value = value; 189 AccessInternal::store_at<decorators | INTERNAL_VALUE_IS_OOP>(base, offset, oop_value); 190 } 191 192 template <typename T> 193 static inline T oop_atomic_cmpxchg_at(oop base, ptrdiff_t offset, T compare_value, T new_value) { 194 verify_heap_oop_decorators<atomic_cmpxchg_mo_decorators>(); 195 typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType; 196 OopType new_oop_value = new_value; 197 OopType compare_oop_value = compare_value; 198 return AccessInternal::atomic_cmpxchg_at<decorators | INTERNAL_VALUE_IS_OOP>(base, offset, compare_oop_value, new_oop_value); 199 } 200 201 template <typename T> 202 static inline T oop_atomic_xchg_at(oop base, ptrdiff_t offset, T new_value) { 203 verify_heap_oop_decorators<atomic_xchg_mo_decorators>(); 204 typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType; 205 OopType new_oop_value = new_value; 206 return AccessInternal::atomic_xchg_at<decorators | INTERNAL_VALUE_IS_OOP>(base, offset, new_oop_value); 207 } 208 209 // Clone an object from src to dst 210 static inline void clone(oop src, oop dst, size_t size) { 211 verify_decorators<IN_HEAP>(); 212 AccessInternal::clone<decorators>(src, dst, size); 213 } 214 215 // Primitive accesses 216 template <typename P> 217 static inline P load(P* addr) { 218 verify_primitive_decorators<load_mo_decorators>(); 219 return AccessInternal::load<decorators, P, P>(addr); 220 } 221 222 template <typename P, typename T> 223 static inline void store(P* addr, T value) { 224 verify_primitive_decorators<store_mo_decorators>(); 225 AccessInternal::store<decorators>(addr, value); 226 } 227 228 template <typename P, typename T> 229 static inline T atomic_cmpxchg(P* addr, T compare_value, T new_value) { 230 verify_primitive_decorators<atomic_cmpxchg_mo_decorators>(); 231 return AccessInternal::atomic_cmpxchg<decorators>(addr, compare_value, new_value); 232 } 233 234 template <typename P, typename T> 235 static inline T atomic_xchg(P* addr, T new_value) { 236 verify_primitive_decorators<atomic_xchg_mo_decorators>(); 237 return AccessInternal::atomic_xchg<decorators>(addr, new_value); 238 } 239 240 // Oop accesses 241 template <typename P> 242 static inline AccessInternal::OopLoadProxy<P, decorators> oop_load(P* addr) { 243 verify_oop_decorators<load_mo_decorators>(); 244 return AccessInternal::OopLoadProxy<P, decorators>(addr); 245 } 246 247 template <typename P, typename T> 248 static inline void oop_store(P* addr, T value) { 249 verify_oop_decorators<store_mo_decorators>(); 250 typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType; 251 OopType oop_value = value; 252 AccessInternal::store<decorators | INTERNAL_VALUE_IS_OOP>(addr, oop_value); 253 } 254 255 template <typename P, typename T> 256 static inline T oop_atomic_cmpxchg(P* addr, T compare_value, T new_value) { 257 verify_oop_decorators<atomic_cmpxchg_mo_decorators>(); 258 typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType; 259 OopType new_oop_value = new_value; 260 OopType compare_oop_value = compare_value; 261 return AccessInternal::atomic_cmpxchg<decorators | INTERNAL_VALUE_IS_OOP>(addr, compare_oop_value, new_oop_value); 262 } 263 264 template <typename P, typename T> 265 static inline T oop_atomic_xchg(P* addr, T new_value) { 266 verify_oop_decorators<atomic_xchg_mo_decorators>(); 267 typedef typename AccessInternal::OopOrNarrowOop<T>::type OopType; 268 OopType new_oop_value = new_value; 269 return AccessInternal::atomic_xchg<decorators | INTERNAL_VALUE_IS_OOP>(addr, new_oop_value); 270 } 271 }; 272 273 // Helper for performing raw accesses (knows only of memory ordering 274 // atomicity decorators as well as compressed oops). 275 template <DecoratorSet decorators = DECORATORS_NONE> 276 class RawAccess: public Access<AS_RAW | decorators> {}; 277 278 // Helper for performing normal accesses on the heap. These accesses 279 // may resolve an accessor on a GC barrier set. 280 template <DecoratorSet decorators = DECORATORS_NONE> 281 class HeapAccess: public Access<IN_HEAP | decorators> {}; 282 283 // Helper for performing normal accesses in roots. These accesses 284 // may resolve an accessor on a GC barrier set. 285 template <DecoratorSet decorators = DECORATORS_NONE> 286 class NativeAccess: public Access<IN_NATIVE | decorators> {}; 287 288 // Helper for performing accesses in nmethods. These accesses 289 // may resolve an accessor on a GC barrier set. 290 template <DecoratorSet decorators = DECORATORS_NONE> 291 class NMethodAccess: public Access<IN_NMETHOD | decorators> {}; 292 293 // Helper for array access. 294 template <DecoratorSet decorators = DECORATORS_NONE> 295 class ArrayAccess: public HeapAccess<IS_ARRAY | decorators> { 296 typedef HeapAccess<IS_ARRAY | decorators> AccessT; 297 public: 298 template <typename T> 299 static inline void arraycopy(arrayOop src_obj, size_t src_offset_in_bytes, 300 arrayOop dst_obj, size_t dst_offset_in_bytes, 301 size_t length) { 302 AccessT::arraycopy(src_obj, src_offset_in_bytes, static_cast<const T*>(nullptr), 303 dst_obj, dst_offset_in_bytes, static_cast<T*>(nullptr), 304 length); 305 } 306 307 template <typename T> 308 static inline void arraycopy_to_native(arrayOop src_obj, size_t src_offset_in_bytes, 309 T* dst, 310 size_t length) { 311 AccessT::arraycopy(src_obj, src_offset_in_bytes, static_cast<const T*>(nullptr), 312 nullptr, 0, dst, 313 length); 314 } 315 316 template <typename T> 317 static inline void arraycopy_from_native(const T* src, 318 arrayOop dst_obj, size_t dst_offset_in_bytes, 319 size_t length) { 320 AccessT::arraycopy(nullptr, 0, src, 321 dst_obj, dst_offset_in_bytes, static_cast<T*>(nullptr), 322 length); 323 } 324 325 static inline bool oop_arraycopy(arrayOop src_obj, size_t src_offset_in_bytes, 326 arrayOop dst_obj, size_t dst_offset_in_bytes, 327 size_t length) { 328 return AccessT::oop_arraycopy(src_obj, src_offset_in_bytes, static_cast<const HeapWord*>(nullptr), 329 dst_obj, dst_offset_in_bytes, static_cast<HeapWord*>(nullptr), 330 length); 331 } 332 333 template <typename T> 334 static inline bool oop_arraycopy_raw(T* src, T* dst, size_t length) { 335 return AccessT::oop_arraycopy(nullptr, 0, src, 336 nullptr, 0, dst, 337 length); 338 } 339 340 }; 341 342 template <DecoratorSet decorators> 343 template <DecoratorSet expected_decorators> 344 void Access<decorators>::verify_decorators() { 345 STATIC_ASSERT((~expected_decorators & decorators) == 0); // unexpected decorator used 346 const DecoratorSet barrier_strength_decorators = decorators & AS_DECORATOR_MASK; 347 STATIC_ASSERT(barrier_strength_decorators == 0 || ( // make sure barrier strength decorators are disjoint if set 348 (barrier_strength_decorators ^ AS_NO_KEEPALIVE) == 0 || 349 (barrier_strength_decorators ^ AS_RAW) == 0 || 350 (barrier_strength_decorators ^ AS_NORMAL) == 0 351 )); 352 const DecoratorSet ref_strength_decorators = decorators & ON_DECORATOR_MASK; 353 STATIC_ASSERT(ref_strength_decorators == 0 || ( // make sure ref strength decorators are disjoint if set 354 (ref_strength_decorators ^ ON_STRONG_OOP_REF) == 0 || 355 (ref_strength_decorators ^ ON_WEAK_OOP_REF) == 0 || 356 (ref_strength_decorators ^ ON_PHANTOM_OOP_REF) == 0 || 357 (ref_strength_decorators ^ ON_UNKNOWN_OOP_REF) == 0 358 )); 359 const DecoratorSet memory_ordering_decorators = decorators & MO_DECORATOR_MASK; 360 STATIC_ASSERT(memory_ordering_decorators == 0 || ( // make sure memory ordering decorators are disjoint if set 361 (memory_ordering_decorators ^ MO_UNORDERED) == 0 || 362 (memory_ordering_decorators ^ MO_RELAXED) == 0 || 363 (memory_ordering_decorators ^ MO_ACQUIRE) == 0 || 364 (memory_ordering_decorators ^ MO_RELEASE) == 0 || 365 (memory_ordering_decorators ^ MO_SEQ_CST) == 0 366 )); 367 const DecoratorSet location_decorators = decorators & IN_DECORATOR_MASK; 368 STATIC_ASSERT(location_decorators == 0 || ( // make sure location decorators are disjoint if set 369 (location_decorators ^ IN_NATIVE) == 0 || 370 (location_decorators ^ IN_NMETHOD) == 0 || 371 (location_decorators ^ IN_HEAP) == 0 372 )); 373 } 374 375 #endif // SHARE_OOPS_ACCESS_HPP