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