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