1 /*
2 * Copyright (c) 2014, 2017, 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang.invoke;
27
28 import jdk.internal.HotSpotIntrinsicCandidate;
29 import jdk.internal.util.Preconditions;
30 import jdk.internal.vm.annotation.ForceInline;
31 import jdk.internal.vm.annotation.Stable;
32
33 import java.lang.reflect.Method;
34 import java.util.HashMap;
35 import java.util.List;
36 import java.util.Map;
37 import java.util.function.BiFunction;
38 import java.util.function.Function;
39
40 import static java.lang.invoke.MethodHandleStatics.UNSAFE;
41 import static java.lang.invoke.MethodHandleStatics.newInternalError;
42
43 /**
44 * A VarHandle is a dynamically strongly typed reference to a variable, or to a
45 * parametrically-defined family of variables, including static fields,
46 * non-static fields, array elements, or components of an off-heap data
47 * structure. Access to such variables is supported under various
48 * <em>access modes</em>, including plain read/write access, volatile
49 * read/write access, and compare-and-swap.
50 *
51 * <p>VarHandles are immutable and have no visible state. VarHandles cannot be
52 * subclassed by the user.
53 *
54 * <p>A VarHandle has:
55 * <ul>
56 * <li>a {@link #varType variable type} T, the type of every variable referenced
57 * by this VarHandle; and
58 * <li>a list of {@link #coordinateTypes coordinate types}
59 * {@code CT1, CT2, ..., CTn}, the types of <em>coordinate expressions</em> that
60 * jointly locate a variable referenced by this VarHandle.
61 * </ul>
62 * Variable and coordinate types may be primitive or reference, and are
63 * represented by {@code Class} objects. The list of coordinate types may be
64 * empty.
65 *
66 * <p>Factory methods that produce or {@link java.lang.invoke.MethodHandles.Lookup
67 * lookup} VarHandle instances document the supported variable type and the list
68 * of coordinate types.
69 *
70 * <p>Each access mode is associated with one <em>access mode method</em>, a
71 * <a href="MethodHandle.html#sigpoly">signature polymorphic</a> method named
72 * for the access mode. When an access mode method is invoked on a VarHandle
73 * instance, the initial arguments to the invocation are coordinate expressions
74 * that indicate in precisely which object the variable is to be accessed.
75 * Trailing arguments to the invocation represent values of importance to the
76 * access mode. For example, the various compare-and-set or compare-and-exchange
77 * access modes require two trailing arguments for the variable's expected value
78 * and new value.
79 *
80 * <p>The arity and types of arguments to the invocation of an access mode
81 * method are not checked statically. Instead, each access mode method
82 * specifies an {@link #accessModeType(AccessMode) access mode type},
83 * represented as an instance of {@link MethodType}, that serves as a kind of
84 * method signature against which the arguments are checked dynamically. An
85 * access mode type gives formal parameter types in terms of the coordinate
86 * types of a VarHandle instance and the types for values of importance to the
87 * access mode. An access mode type also gives a return type, often in terms of
88 * the variable type of a VarHandle instance. When an access mode method is
89 * invoked on a VarHandle instance, the symbolic type descriptor at the
90 * call site, the run time types of arguments to the invocation, and the run
91 * time type of the return value, must <a href="#invoke">match</a> the types
92 * given in the access mode type. A runtime exception will be thrown if the
93 * match fails.
94 *
95 * For example, the access mode method {@link #compareAndSet} specifies that if
96 * its receiver is a VarHandle instance with coordinate types
97 * {@code CT1, ..., CTn} and variable type {@code T}, then its access mode type
98 * is {@code (CT1 c1, ..., CTn cn, T expectedValue, T newValue)boolean}.
99 * Suppose that a VarHandle instance can access array elements, and that its
100 * coordinate types are {@code String[]} and {@code int} while its variable type
101 * is {@code String}. The access mode type for {@code compareAndSet} on this
102 * VarHandle instance would be
103 * {@code (String[] c1, int c2, String expectedValue, String newValue)boolean}.
104 * Such a VarHandle instance may produced by the
105 * {@link MethodHandles#arrayElementVarHandle(Class) array factory method} and
106 * access array elements as follows:
107 * <pre> {@code
108 * String[] sa = ...
109 * VarHandle avh = MethodHandles.arrayElementVarHandle(String[].class);
110 * boolean r = avh.compareAndSet(sa, 10, "expected", "new");
111 * }</pre>
112 *
113 * <p>Access modes are grouped into the following categories:
114 * <ul>
115 * <li>read access modes that get the value of a variable under specified
116 * memory ordering effects.
117 * The set of corresponding access mode methods belonging to this group
118 * consists of the methods
119 * {@link #get get},
120 * {@link #getVolatile getVolatile},
121 * {@link #getAcquire getAcquire},
122 * {@link #getOpaque getOpaque}.
123 * <li>write access modes that set the value of a variable under specified
124 * memory ordering effects.
125 * The set of corresponding access mode methods belonging to this group
126 * consists of the methods
127 * {@link #set set},
128 * {@link #setVolatile setVolatile},
129 * {@link #setRelease setRelease},
130 * {@link #setOpaque setOpaque}.
131 * <li>atomic update access modes that, for example, atomically compare and set
132 * the value of a variable under specified memory ordering effects.
133 * The set of corresponding access mode methods belonging to this group
134 * consists of the methods
135 * {@link #compareAndSet compareAndSet},
136 * {@link #weakCompareAndSetPlain weakCompareAndSetPlain},
137 * {@link #weakCompareAndSet weakCompareAndSet},
138 * {@link #weakCompareAndSetAcquire weakCompareAndSetAcquire},
139 * {@link #weakCompareAndSetRelease weakCompareAndSetRelease},
140 * {@link #compareAndExchangeAcquire compareAndExchangeAcquire},
141 * {@link #compareAndExchange compareAndExchange},
142 * {@link #compareAndExchangeRelease compareAndExchangeRelease},
143 * {@link #getAndSet getAndSet},
144 * {@link #getAndSetAcquire getAndSetAcquire},
145 * {@link #getAndSetRelease getAndSetRelease}.
146 * <li>numeric atomic update access modes that, for example, atomically get and
147 * set with addition the value of a variable under specified memory ordering
148 * effects.
149 * The set of corresponding access mode methods belonging to this group
150 * consists of the methods
151 * {@link #getAndAdd getAndAdd},
152 * {@link #getAndAddAcquire getAndAddAcquire},
153 * {@link #getAndAddRelease getAndAddRelease},
154 * <li>bitwise atomic update access modes that, for example, atomically get and
155 * bitwise OR the value of a variable under specified memory ordering
156 * effects.
157 * The set of corresponding access mode methods belonging to this group
158 * consists of the methods
159 * {@link #getAndBitwiseOr getAndBitwiseOr},
160 * {@link #getAndBitwiseOrAcquire getAndBitwiseOrAcquire},
161 * {@link #getAndBitwiseOrRelease getAndBitwiseOrRelease},
162 * {@link #getAndBitwiseAnd getAndBitwiseAnd},
163 * {@link #getAndBitwiseAndAcquire getAndBitwiseAndAcquire},
164 * {@link #getAndBitwiseAndRelease getAndBitwiseAndRelease},
165 * {@link #getAndBitwiseXor getAndBitwiseXor},
166 * {@link #getAndBitwiseXorAcquire getAndBitwiseXorAcquire},
167 * {@link #getAndBitwiseXorRelease getAndBitwiseXorRelease}.
168 * </ul>
169 *
170 * <p>Factory methods that produce or {@link java.lang.invoke.MethodHandles.Lookup
171 * lookup} VarHandle instances document the set of access modes that are
172 * supported, which may also include documenting restrictions based on the
173 * variable type and whether a variable is read-only. If an access mode is not
174 * supported then the corresponding access mode method will on invocation throw
175 * an {@code UnsupportedOperationException}. Factory methods should document
176 * any additional undeclared exceptions that may be thrown by access mode
177 * methods.
178 * The {@link #get get} access mode is supported for all
179 * VarHandle instances and the corresponding method never throws
180 * {@code UnsupportedOperationException}.
181 * If a VarHandle references a read-only variable (for example a {@code final}
182 * field) then write, atomic update, numeric atomic update, and bitwise atomic
183 * update access modes are not supported and corresponding methods throw
184 * {@code UnsupportedOperationException}.
185 * Read/write access modes (if supported), with the exception of
186 * {@code get} and {@code set}, provide atomic access for
187 * reference types and all primitive types.
188 * Unless stated otherwise in the documentation of a factory method, the access
189 * modes {@code get} and {@code set} (if supported) provide atomic access for
190 * reference types and all primitives types, with the exception of {@code long}
191 * and {@code double} on 32-bit platforms.
192 *
193 * <p>Access modes will override any memory ordering effects specified at
194 * the declaration site of a variable. For example, a VarHandle accessing a
195 * a field using the {@code get} access mode will access the field as
196 * specified <em>by its access mode</em> even if that field is declared
197 * {@code volatile}. When mixed access is performed extreme care should be
198 * taken since the Java Memory Model may permit surprising results.
199 *
200 * <p>In addition to supporting access to variables under various access modes,
201 * a set of static methods, referred to as memory fence methods, is also
202 * provided for fine-grained control of memory ordering.
203 *
204 * The Java Language Specification permits other threads to observe operations
205 * as if they were executed in orders different than are apparent in program
206 * source code, subject to constraints arising, for example, from the use of
207 * locks, {@code volatile} fields or VarHandles. The static methods,
208 * {@link #fullFence fullFence}, {@link #acquireFence acquireFence},
209 * {@link #releaseFence releaseFence}, {@link #loadLoadFence loadLoadFence} and
210 * {@link #storeStoreFence storeStoreFence}, can also be used to impose
211 * constraints. Their specifications, as is the case for certain access modes,
212 * are phrased in terms of the lack of "reorderings" -- observable ordering
213 * effects that might otherwise occur if the fence was not present. More
214 * precise phrasing of the specification of access mode methods and memory fence
215 * methods may accompany future updates of the Java Language Specification.
216 *
217 * <h1>Compiling invocation of access mode methods</h1>
218 * A Java method call expression naming an access mode method can invoke a
219 * VarHandle from Java source code. From the viewpoint of source code, these
220 * methods can take any arguments and their polymorphic result (if expressed)
221 * can be cast to any return type. Formally this is accomplished by giving the
222 * access mode methods variable arity {@code Object} arguments and
223 * {@code Object} return types (if the return type is polymorphic), but they
224 * have an additional quality called <em>signature polymorphism</em> which
225 * connects this freedom of invocation directly to the JVM execution stack.
226 * <p>
227 * As is usual with virtual methods, source-level calls to access mode methods
228 * compile to an {@code invokevirtual} instruction. More unusually, the
229 * compiler must record the actual argument types, and may not perform method
230 * invocation conversions on the arguments. Instead, it must generate
231 * instructions to push them on the stack according to their own unconverted
232 * types. The VarHandle object itself will be pushed on the stack before the
233 * arguments. The compiler then generates an {@code invokevirtual} instruction
234 * that invokes the access mode method with a symbolic type descriptor which
235 * describes the argument and return types.
236 * <p>
237 * To issue a complete symbolic type descriptor, the compiler must also
238 * determine the return type (if polymorphic). This is based on a cast on the
239 * method invocation expression, if there is one, or else {@code Object} if the
240 * invocation is an expression, or else {@code void} if the invocation is a
241 * statement. The cast may be to a primitive type (but not {@code void}).
242 * <p>
243 * As a corner case, an uncasted {@code null} argument is given a symbolic type
244 * descriptor of {@code java.lang.Void}. The ambiguity with the type
245 * {@code Void} is harmless, since there are no references of type {@code Void}
246 * except the null reference.
247 *
248 *
249 * <h1><a id="invoke">Performing invocation of access mode methods</a></h1>
250 * The first time an {@code invokevirtual} instruction is executed it is linked
251 * by symbolically resolving the names in the instruction and verifying that
252 * the method call is statically legal. This also holds for calls to access mode
253 * methods. In this case, the symbolic type descriptor emitted by the compiler
254 * is checked for correct syntax, and names it contains are resolved. Thus, an
255 * {@code invokevirtual} instruction which invokes an access mode method will
256 * always link, as long as the symbolic type descriptor is syntactically
257 * well-formed and the types exist.
258 * <p>
259 * When the {@code invokevirtual} is executed after linking, the receiving
260 * VarHandle's access mode type is first checked by the JVM to ensure that it
261 * matches the symbolic type descriptor. If the type
262 * match fails, it means that the access mode method which the caller is
263 * invoking is not present on the individual VarHandle being invoked.
264 *
265 * <p>
266 * Invocation of an access mode method behaves as if an invocation of
267 * {@link MethodHandle#invoke}, where the receiving method handle accepts the
268 * VarHandle instance as the leading argument. More specifically, the
269 * following, where {@code {access-mode}} corresponds to the access mode method
270 * name:
271 * <pre> {@code
272 * VarHandle vh = ..
273 * R r = (R) vh.{access-mode}(p1, p2, ..., pN);
274 * }</pre>
275 * behaves as if:
276 * <pre> {@code
277 * VarHandle vh = ..
278 * VarHandle.AccessMode am = VarHandle.AccessMode.valueFromMethodName("{access-mode}");
279 * MethodHandle mh = MethodHandles.varHandleExactInvoker(
280 * am,
281 * vh.accessModeType(am));
282 *
283 * R r = (R) mh.invoke(vh, p1, p2, ..., pN)
284 * }</pre>
285 * (modulo access mode methods do not declare throwing of {@code Throwable}).
286 * This is equivalent to:
287 * <pre> {@code
288 * MethodHandle mh = MethodHandles.lookup().findVirtual(
289 * VarHandle.class,
290 * "{access-mode}",
291 * MethodType.methodType(R, p1, p2, ..., pN));
292 *
293 * R r = (R) mh.invokeExact(vh, p1, p2, ..., pN)
294 * }</pre>
295 * where the desired method type is the symbolic type descriptor and a
296 * {@link MethodHandle#invokeExact} is performed, since before invocation of the
297 * target, the handle will apply reference casts as necessary and box, unbox, or
298 * widen primitive values, as if by {@link MethodHandle#asType asType} (see also
299 * {@link MethodHandles#varHandleInvoker}).
300 *
301 * More concisely, such behaviour is equivalent to:
302 * <pre> {@code
303 * VarHandle vh = ..
304 * VarHandle.AccessMode am = VarHandle.AccessMode.valueFromMethodName("{access-mode}");
305 * MethodHandle mh = vh.toMethodHandle(am);
306 *
307 * R r = (R) mh.invoke(p1, p2, ..., pN)
308 * }</pre>
309 * Where, in this case, the method handle is bound to the VarHandle instance.
310 *
311 *
312 * <h1>Invocation checking</h1>
313 * In typical programs, VarHandle access mode type matching will usually
314 * succeed. But if a match fails, the JVM will throw a
315 * {@link WrongMethodTypeException}.
316 * <p>
317 * Thus, an access mode type mismatch which might show up as a linkage error
318 * in a statically typed program can show up as a dynamic
319 * {@code WrongMethodTypeException} in a program which uses VarHandles.
320 * <p>
321 * Because access mode types contain "live" {@code Class} objects, method type
322 * matching takes into account both type names and class loaders.
323 * Thus, even if a VarHandle {@code VH} is created in one class loader
324 * {@code L1} and used in another {@code L2}, VarHandle access mode method
325 * calls are type-safe, because the caller's symbolic type descriptor, as
326 * resolved in {@code L2}, is matched against the original callee method's
327 * symbolic type descriptor, as resolved in {@code L1}. The resolution in
328 * {@code L1} happens when {@code VH} is created and its access mode types are
329 * assigned, while the resolution in {@code L2} happens when the
330 * {@code invokevirtual} instruction is linked.
331 * <p>
332 * Apart from type descriptor checks, a VarHandles's capability to
333 * access it's variables is unrestricted.
334 * If a VarHandle is formed on a non-public variable by a class that has access
335 * to that variable, the resulting VarHandle can be used in any place by any
336 * caller who receives a reference to it.
337 * <p>
338 * Unlike with the Core Reflection API, where access is checked every time a
339 * reflective method is invoked, VarHandle access checking is performed
340 * <a href="MethodHandles.Lookup.html#access">when the VarHandle is
341 * created</a>.
342 * Thus, VarHandles to non-public variables, or to variables in non-public
343 * classes, should generally be kept secret. They should not be passed to
344 * untrusted code unless their use from the untrusted code would be harmless.
345 *
346 *
347 * <h1>VarHandle creation</h1>
348 * Java code can create a VarHandle that directly accesses any field that is
349 * accessible to that code. This is done via a reflective, capability-based
350 * API called {@link java.lang.invoke.MethodHandles.Lookup
351 * MethodHandles.Lookup}.
352 * For example, a VarHandle for a non-static field can be obtained
353 * from {@link java.lang.invoke.MethodHandles.Lookup#findVarHandle
354 * Lookup.findVarHandle}.
355 * There is also a conversion method from Core Reflection API objects,
356 * {@link java.lang.invoke.MethodHandles.Lookup#unreflectVarHandle
357 * Lookup.unreflectVarHandle}.
358 * <p>
359 * Access to protected field members is restricted to receivers only of the
360 * accessing class, or one of its subclasses, and the accessing class must in
361 * turn be a subclass (or package sibling) of the protected member's defining
362 * class. If a VarHandle refers to a protected non-static field of a declaring
363 * class outside the current package, the receiver argument will be narrowed to
364 * the type of the accessing class.
365 *
366 * <h1>Interoperation between VarHandles and the Core Reflection API</h1>
367 * Using factory methods in the {@link java.lang.invoke.MethodHandles.Lookup
368 * Lookup} API, any field represented by a Core Reflection API object
369 * can be converted to a behaviorally equivalent VarHandle.
370 * For example, a reflective {@link java.lang.reflect.Field Field} can
371 * be converted to a VarHandle using
372 * {@link java.lang.invoke.MethodHandles.Lookup#unreflectVarHandle
373 * Lookup.unreflectVarHandle}.
374 * The resulting VarHandles generally provide more direct and efficient
375 * access to the underlying fields.
376 * <p>
377 * As a special case, when the Core Reflection API is used to view the
378 * signature polymorphic access mode methods in this class, they appear as
379 * ordinary non-polymorphic methods. Their reflective appearance, as viewed by
380 * {@link java.lang.Class#getDeclaredMethod Class.getDeclaredMethod},
381 * is unaffected by their special status in this API.
382 * For example, {@link java.lang.reflect.Method#getModifiers
383 * Method.getModifiers}
384 * will report exactly those modifier bits required for any similarly
385 * declared method, including in this case {@code native} and {@code varargs}
386 * bits.
387 * <p>
388 * As with any reflected method, these methods (when reflected) may be invoked
389 * directly via {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke},
390 * via JNI, or indirectly via
391 * {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect}.
392 * However, such reflective calls do not result in access mode method
393 * invocations. Such a call, if passed the required argument (a single one, of
394 * type {@code Object[]}), will ignore the argument and will throw an
395 * {@code UnsupportedOperationException}.
396 * <p>
397 * Since {@code invokevirtual} instructions can natively invoke VarHandle
398 * access mode methods under any symbolic type descriptor, this reflective view
399 * conflicts with the normal presentation of these methods via bytecodes.
400 * Thus, these native methods, when reflectively viewed by
401 * {@code Class.getDeclaredMethod}, may be regarded as placeholders only.
402 * <p>
403 * In order to obtain an invoker method for a particular access mode type,
404 * use {@link java.lang.invoke.MethodHandles#varHandleExactInvoker} or
405 * {@link java.lang.invoke.MethodHandles#varHandleInvoker}. The
406 * {@link java.lang.invoke.MethodHandles.Lookup#findVirtual Lookup.findVirtual}
407 * API is also able to return a method handle to call an access mode method for
408 * any specified access mode type and is equivalent in behaviour to
409 * {@link java.lang.invoke.MethodHandles#varHandleInvoker}.
410 *
411 * <h1>Interoperation between VarHandles and Java generics</h1>
412 * A VarHandle can be obtained for a variable, such as a a field, which is
413 * declared with Java generic types. As with the Core Reflection API, the
414 * VarHandle's variable type will be constructed from the erasure of the
415 * source-level type. When a VarHandle access mode method is invoked, the
416 * types
417 * of its arguments or the return value cast type may be generic types or type
418 * instances. If this occurs, the compiler will replace those types by their
419 * erasures when it constructs the symbolic type descriptor for the
420 * {@code invokevirtual} instruction.
421 *
422 * @see MethodHandle
423 * @see MethodHandles
424 * @see MethodType
425 * @since 9
426 */
427 public abstract class VarHandle {
428 final VarForm vform;
429
430 VarHandle(VarForm vform) {
431 this.vform = vform;
432 }
433
434 RuntimeException unsupported() {
435 return new UnsupportedOperationException();
436 }
437
438 // Plain accessors
439
440 /**
441 * Returns the value of a variable, with memory semantics of reading as
442 * if the variable was declared non-{@code volatile}. Commonly referred to
443 * as plain read access.
444 *
445 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn)T}.
446 *
447 * <p>The symbolic type descriptor at the call site of {@code get}
448 * must match the access mode type that is the result of calling
449 * {@code accessModeType(VarHandle.AccessMode.GET)} on this VarHandle.
450 *
451 * <p>This access mode is supported by all VarHandle instances and never
452 * throws {@code UnsupportedOperationException}.
453 *
454 * @param args the signature-polymorphic parameter list of the form
455 * {@code (CT1 ct1, ..., CTn)}
456 * , statically represented using varargs.
457 * @return the signature-polymorphic result that is the value of the
458 * variable
459 * , statically represented using {@code Object}.
460 * @throws WrongMethodTypeException if the access mode type does not
461 * match the caller's symbolic type descriptor.
462 * @throws ClassCastException if the access mode type matches the caller's
463 * symbolic type descriptor, but a reference cast fails.
464 */
465 public final native
466 @MethodHandle.PolymorphicSignature
467 @HotSpotIntrinsicCandidate
468 Object get(Object... args);
469
470 /**
471 * Sets the value of a variable to the {@code newValue}, with memory
472 * semantics of setting as if the variable was declared non-{@code volatile}
473 * and non-{@code final}. Commonly referred to as plain write access.
474 *
475 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T newValue)void}
476 *
477 * <p>The symbolic type descriptor at the call site of {@code set}
478 * must match the access mode type that is the result of calling
479 * {@code accessModeType(VarHandle.AccessMode.SET)} on this VarHandle.
480 *
481 * @param args the signature-polymorphic parameter list of the form
482 * {@code (CT1 ct1, ..., CTn ctn, T newValue)}
483 * , statically represented using varargs.
484 * @throws UnsupportedOperationException if the access mode is unsupported
485 * for this VarHandle.
486 * @throws WrongMethodTypeException if the access mode type does not
487 * match the caller's symbolic type descriptor.
488 * @throws ClassCastException if the access mode type matches the caller's
489 * symbolic type descriptor, but a reference cast fails.
490 */
491 public final native
492 @MethodHandle.PolymorphicSignature
493 @HotSpotIntrinsicCandidate
494 void set(Object... args);
495
496
497 // Volatile accessors
498
499 /**
500 * Returns the value of a variable, with memory semantics of reading as if
501 * the variable was declared {@code volatile}.
502 *
503 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn)T}.
504 *
505 * <p>The symbolic type descriptor at the call site of {@code getVolatile}
506 * must match the access mode type that is the result of calling
507 * {@code accessModeType(VarHandle.AccessMode.GET_VOLATILE)} on this
508 * VarHandle.
509 *
510 * @param args the signature-polymorphic parameter list of the form
511 * {@code (CT1 ct1, ..., CTn ctn)}
512 * , statically represented using varargs.
513 * @return the signature-polymorphic result that is the value of the
514 * variable
515 * , statically represented using {@code Object}.
516 * @throws UnsupportedOperationException if the access mode is unsupported
517 * for this VarHandle.
518 * @throws WrongMethodTypeException if the access mode type does not
519 * match the caller's symbolic type descriptor.
520 * @throws ClassCastException if the access mode type matches the caller's
521 * symbolic type descriptor, but a reference cast fails.
522 */
523 public final native
524 @MethodHandle.PolymorphicSignature
525 @HotSpotIntrinsicCandidate
526 Object getVolatile(Object... args);
527
528 /**
529 * Sets the value of a variable to the {@code newValue}, with memory
530 * semantics of setting as if the variable was declared {@code volatile}.
531 *
532 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T newValue)void}.
533 *
534 * <p>The symbolic type descriptor at the call site of {@code setVolatile}
535 * must match the access mode type that is the result of calling
536 * {@code accessModeType(VarHandle.AccessMode.SET_VOLATILE)} on this
537 * VarHandle.
538 *
539 * @apiNote
540 * Ignoring the many semantic differences from C and C++, this method has
541 * memory ordering effects compatible with {@code memory_order_seq_cst}.
542 *
543 * @param args the signature-polymorphic parameter list of the form
544 * {@code (CT1 ct1, ..., CTn ctn, T newValue)}
545 * , statically represented using varargs.
546 * @throws UnsupportedOperationException if the access mode is unsupported
547 * for this VarHandle.
548 * @throws WrongMethodTypeException if the access mode type does not
549 * match the caller's symbolic type descriptor.
550 * @throws ClassCastException if the access mode type matches the caller's
551 * symbolic type descriptor, but a reference cast fails.
552 */
553 public final native
554 @MethodHandle.PolymorphicSignature
555 @HotSpotIntrinsicCandidate
556 void setVolatile(Object... args);
557
558
559 /**
560 * Returns the value of a variable, accessed in program order, but with no
561 * assurance of memory ordering effects with respect to other threads.
562 *
563 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn)T}.
564 *
565 * <p>The symbolic type descriptor at the call site of {@code getOpaque}
566 * must match the access mode type that is the result of calling
567 * {@code accessModeType(VarHandle.AccessMode.GET_OPAQUE)} on this
568 * VarHandle.
569 *
570 * @param args the signature-polymorphic parameter list of the form
571 * {@code (CT1 ct1, ..., CTn ctn)}
572 * , statically represented using varargs.
573 * @return the signature-polymorphic result that is the value of the
574 * variable
575 * , statically represented using {@code Object}.
576 * @throws UnsupportedOperationException if the access mode is unsupported
577 * for this VarHandle.
578 * @throws WrongMethodTypeException if the access mode type does not
579 * match the caller's symbolic type descriptor.
580 * @throws ClassCastException if the access mode type matches the caller's
581 * symbolic type descriptor, but a reference cast fails.
582 */
583 public final native
584 @MethodHandle.PolymorphicSignature
585 @HotSpotIntrinsicCandidate
586 Object getOpaque(Object... args);
587
588 /**
589 * Sets the value of a variable to the {@code newValue}, in program order,
590 * but with no assurance of memory ordering effects with respect to other
591 * threads.
592 *
593 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T newValue)void}.
594 *
595 * <p>The symbolic type descriptor at the call site of {@code setOpaque}
596 * must match the access mode type that is the result of calling
597 * {@code accessModeType(VarHandle.AccessMode.SET_OPAQUE)} on this
598 * VarHandle.
599 *
600 * @param args the signature-polymorphic parameter list of the form
601 * {@code (CT1 ct1, ..., CTn ctn, T newValue)}
602 * , statically represented using varargs.
603 * @throws UnsupportedOperationException if the access mode is unsupported
604 * for this VarHandle.
605 * @throws WrongMethodTypeException if the access mode type does not
606 * match the caller's symbolic type descriptor.
607 * @throws ClassCastException if the access mode type matches the caller's
608 * symbolic type descriptor, but a reference cast fails.
609 */
610 public final native
611 @MethodHandle.PolymorphicSignature
612 @HotSpotIntrinsicCandidate
613 void setOpaque(Object... args);
614
615
616 // Lazy accessors
617
618 /**
619 * Returns the value of a variable, and ensures that subsequent loads and
620 * stores are not reordered before this access.
621 *
622 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn)T}.
623 *
624 * <p>The symbolic type descriptor at the call site of {@code getAcquire}
625 * must match the access mode type that is the result of calling
626 * {@code accessModeType(VarHandle.AccessMode.GET_ACQUIRE)} on this
627 * VarHandle.
628 *
629 * @apiNote
630 * Ignoring the many semantic differences from C and C++, this method has
631 * memory ordering effects compatible with {@code memory_order_acquire}
632 * ordering.
633 *
634 * @param args the signature-polymorphic parameter list of the form
635 * {@code (CT1 ct1, ..., CTn ctn)}
636 * , statically represented using varargs.
637 * @return the signature-polymorphic result that is the value of the
638 * variable
639 * , statically represented using {@code Object}.
640 * @throws UnsupportedOperationException if the access mode is unsupported
641 * for this VarHandle.
642 * @throws WrongMethodTypeException if the access mode type does not
643 * match the caller's symbolic type descriptor.
644 * @throws ClassCastException if the access mode type matches the caller's
645 * symbolic type descriptor, but a reference cast fails.
646 */
647 public final native
648 @MethodHandle.PolymorphicSignature
649 @HotSpotIntrinsicCandidate
650 Object getAcquire(Object... args);
651
652 /**
653 * Sets the value of a variable to the {@code newValue}, and ensures that
654 * prior loads and stores are not reordered after this access.
655 *
656 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T newValue)void}.
657 *
658 * <p>The symbolic type descriptor at the call site of {@code setRelease}
659 * must match the access mode type that is the result of calling
660 * {@code accessModeType(VarHandle.AccessMode.SET_RELEASE)} on this
661 * VarHandle.
662 *
663 * @apiNote
664 * Ignoring the many semantic differences from C and C++, this method has
665 * memory ordering effects compatible with {@code memory_order_release}
666 * ordering.
667 *
668 * @param args the signature-polymorphic parameter list of the form
669 * {@code (CT1 ct1, ..., CTn ctn, T newValue)}
670 * , statically represented using varargs.
671 * @throws UnsupportedOperationException if the access mode is unsupported
672 * for this VarHandle.
673 * @throws WrongMethodTypeException if the access mode type does not
674 * match the caller's symbolic type descriptor.
675 * @throws ClassCastException if the access mode type matches the caller's
676 * symbolic type descriptor, but a reference cast fails.
677 */
678 public final native
679 @MethodHandle.PolymorphicSignature
680 @HotSpotIntrinsicCandidate
681 void setRelease(Object... args);
682
683
684 // Compare and set accessors
685
686 /**
687 * Atomically sets the value of a variable to the {@code newValue} with the
688 * memory semantics of {@link #setVolatile} if the variable's current value,
689 * referred to as the <em>witness value</em>, {@code ==} the
690 * {@code expectedValue}, as accessed with the memory semantics of
691 * {@link #getVolatile}.
692 *
693 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)boolean}.
694 *
695 * <p>The symbolic type descriptor at the call site of {@code
696 * compareAndSet} must match the access mode type that is the result of
697 * calling {@code accessModeType(VarHandle.AccessMode.COMPARE_AND_SET)} on
698 * this VarHandle.
699 *
700 * @param args the signature-polymorphic parameter list of the form
701 * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
702 * , statically represented using varargs.
703 * @return {@code true} if successful, otherwise {@code false} if the
704 * witness value was not the same as the {@code expectedValue}.
705 * @throws UnsupportedOperationException if the access mode is unsupported
706 * for this VarHandle.
707 * @throws WrongMethodTypeException if the access mode type does not
708 * match the caller's symbolic type descriptor.
709 * @throws ClassCastException if the access mode type matches the caller's
710 * symbolic type descriptor, but a reference cast fails.
711 * @see #setVolatile(Object...)
712 * @see #getVolatile(Object...)
713 */
714 public final native
715 @MethodHandle.PolymorphicSignature
716 @HotSpotIntrinsicCandidate
717 boolean compareAndSet(Object... args);
718
719 /**
720 * Atomically sets the value of a variable to the {@code newValue} with the
721 * memory semantics of {@link #setVolatile} if the variable's current value,
722 * referred to as the <em>witness value</em>, {@code ==} the
723 * {@code expectedValue}, as accessed with the memory semantics of
724 * {@link #getVolatile}.
725 *
726 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)T}.
727 *
728 * <p>The symbolic type descriptor at the call site of {@code
729 * compareAndExchange}
730 * must match the access mode type that is the result of calling
731 * {@code accessModeType(VarHandle.AccessMode.COMPARE_AND_EXCHANGE)}
732 * on this VarHandle.
733 *
734 * @param args the signature-polymorphic parameter list of the form
735 * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
736 * , statically represented using varargs.
737 * @return the signature-polymorphic result that is the witness value, which
738 * will be the same as the {@code expectedValue} if successful
739 * , statically represented using {@code Object}.
740 * @throws UnsupportedOperationException if the access mode is unsupported
741 * for this VarHandle.
742 * @throws WrongMethodTypeException if the access mode type is not
743 * compatible with the caller's symbolic type descriptor.
744 * @throws ClassCastException if the access mode type is compatible with the
745 * caller's symbolic type descriptor, but a reference cast fails.
746 * @see #setVolatile(Object...)
747 * @see #getVolatile(Object...)
748 */
749 public final native
750 @MethodHandle.PolymorphicSignature
751 @HotSpotIntrinsicCandidate
752 Object compareAndExchange(Object... args);
753
754 /**
755 * Atomically sets the value of a variable to the {@code newValue} with the
756 * memory semantics of {@link #set} if the variable's current value,
757 * referred to as the <em>witness value</em>, {@code ==} the
758 * {@code expectedValue}, as accessed with the memory semantics of
759 * {@link #getAcquire}.
760 *
761 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)T}.
762 *
763 * <p>The symbolic type descriptor at the call site of {@code
764 * compareAndExchangeAcquire}
765 * must match the access mode type that is the result of calling
766 * {@code accessModeType(VarHandle.AccessMode.COMPARE_AND_EXCHANGE_ACQUIRE)} on
767 * this VarHandle.
768 *
769 * @param args the signature-polymorphic parameter list of the form
770 * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
771 * , statically represented using varargs.
772 * @return the signature-polymorphic result that is the witness value, which
773 * will be the same as the {@code expectedValue} if successful
774 * , statically represented using {@code Object}.
775 * @throws UnsupportedOperationException if the access mode is unsupported
776 * for this VarHandle.
777 * @throws WrongMethodTypeException if the access mode type does not
778 * match the caller's symbolic type descriptor.
779 * @throws ClassCastException if the access mode type matches the caller's
780 * symbolic type descriptor, but a reference cast fails.
781 * @see #set(Object...)
782 * @see #getAcquire(Object...)
783 */
784 public final native
785 @MethodHandle.PolymorphicSignature
786 @HotSpotIntrinsicCandidate
787 Object compareAndExchangeAcquire(Object... args);
788
789 /**
790 * Atomically sets the value of a variable to the {@code newValue} with the
791 * memory semantics of {@link #setRelease} if the variable's current value,
792 * referred to as the <em>witness value</em>, {@code ==} the
793 * {@code expectedValue}, as accessed with the memory semantics of
794 * {@link #get}.
795 *
796 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)T}.
797 *
798 * <p>The symbolic type descriptor at the call site of {@code
799 * compareAndExchangeRelease}
800 * must match the access mode type that is the result of calling
801 * {@code accessModeType(VarHandle.AccessMode.COMPARE_AND_EXCHANGE_RELEASE)}
802 * on this VarHandle.
803 *
804 * @param args the signature-polymorphic parameter list of the form
805 * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
806 * , statically represented using varargs.
807 * @return the signature-polymorphic result that is the witness value, which
808 * will be the same as the {@code expectedValue} if successful
809 * , statically represented using {@code Object}.
810 * @throws UnsupportedOperationException if the access mode is unsupported
811 * for this VarHandle.
812 * @throws WrongMethodTypeException if the access mode type does not
813 * match the caller's symbolic type descriptor.
814 * @throws ClassCastException if the access mode type matches the caller's
815 * symbolic type descriptor, but a reference cast fails.
816 * @see #setRelease(Object...)
817 * @see #get(Object...)
818 */
819 public final native
820 @MethodHandle.PolymorphicSignature
821 @HotSpotIntrinsicCandidate
822 Object compareAndExchangeRelease(Object... args);
823
824 // Weak (spurious failures allowed)
825
826 /**
827 * Possibly atomically sets the value of a variable to the {@code newValue}
828 * with the semantics of {@link #set} if the variable's current value,
829 * referred to as the <em>witness value</em>, {@code ==} the
830 * {@code expectedValue}, as accessed with the memory semantics of
831 * {@link #get}.
832 *
833 * <p>This operation may fail spuriously (typically, due to memory
834 * contention) even if the witness value does match the expected value.
835 *
836 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)boolean}.
837 *
838 * <p>The symbolic type descriptor at the call site of {@code
839 * weakCompareAndSetPlain} must match the access mode type that is the result of
840 * calling {@code accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET_PLAIN)}
841 * on this VarHandle.
842 *
843 * @param args the signature-polymorphic parameter list of the form
844 * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
845 * , statically represented using varargs.
846 * @return {@code true} if successful, otherwise {@code false} if the
847 * witness value was not the same as the {@code expectedValue} or if this
848 * operation spuriously failed.
849 * @throws UnsupportedOperationException if the access mode is unsupported
850 * for this VarHandle.
851 * @throws WrongMethodTypeException if the access mode type does not
852 * match the caller's symbolic type descriptor.
853 * @throws ClassCastException if the access mode type matches the caller's
854 * symbolic type descriptor, but a reference cast fails.
855 * @see #set(Object...)
856 * @see #get(Object...)
857 */
858 public final native
859 @MethodHandle.PolymorphicSignature
860 @HotSpotIntrinsicCandidate
861 boolean weakCompareAndSetPlain(Object... args);
862
863 /**
864 * Possibly atomically sets the value of a variable to the {@code newValue}
865 * with the memory semantics of {@link #setVolatile} if the variable's
866 * current value, referred to as the <em>witness value</em>, {@code ==} the
867 * {@code expectedValue}, as accessed with the memory semantics of
868 * {@link #getVolatile}.
869 *
870 * <p>This operation may fail spuriously (typically, due to memory
871 * contention) even if the witness value does match the expected value.
872 *
873 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)boolean}.
874 *
875 * <p>The symbolic type descriptor at the call site of {@code
876 * weakCompareAndSet} must match the access mode type that is the
877 * result of calling {@code accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET)}
878 * on this VarHandle.
879 *
880 * @param args the signature-polymorphic parameter list of the form
881 * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
882 * , statically represented using varargs.
883 * @return {@code true} if successful, otherwise {@code false} if the
884 * witness value was not the same as the {@code expectedValue} or if this
885 * operation spuriously failed.
886 * @throws UnsupportedOperationException if the access mode is unsupported
887 * for this VarHandle.
888 * @throws WrongMethodTypeException if the access mode type does not
889 * match the caller's symbolic type descriptor.
890 * @throws ClassCastException if the access mode type matches the caller's
891 * symbolic type descriptor, but a reference cast fails.
892 * @see #setVolatile(Object...)
893 * @see #getVolatile(Object...)
894 */
895 public final native
896 @MethodHandle.PolymorphicSignature
897 @HotSpotIntrinsicCandidate
898 boolean weakCompareAndSet(Object... args);
899
900 /**
901 * Possibly atomically sets the value of a variable to the {@code newValue}
902 * with the semantics of {@link #set} if the variable's current value,
903 * referred to as the <em>witness value</em>, {@code ==} the
904 * {@code expectedValue}, as accessed with the memory semantics of
905 * {@link #getAcquire}.
906 *
907 * <p>This operation may fail spuriously (typically, due to memory
908 * contention) even if the witness value does match the expected value.
909 *
910 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)boolean}.
911 *
912 * <p>The symbolic type descriptor at the call site of {@code
913 * weakCompareAndSetAcquire}
914 * must match the access mode type that is the result of calling
915 * {@code accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET_ACQUIRE)}
916 * on this VarHandle.
917 *
918 * @param args the signature-polymorphic parameter list of the form
919 * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
920 * , statically represented using varargs.
921 * @return {@code true} if successful, otherwise {@code false} if the
922 * witness value was not the same as the {@code expectedValue} or if this
923 * operation spuriously failed.
924 * @throws UnsupportedOperationException if the access mode is unsupported
925 * for this VarHandle.
926 * @throws WrongMethodTypeException if the access mode type does not
927 * match the caller's symbolic type descriptor.
928 * @throws ClassCastException if the access mode type matches the caller's
929 * symbolic type descriptor, but a reference cast fails.
930 * @see #set(Object...)
931 * @see #getAcquire(Object...)
932 */
933 public final native
934 @MethodHandle.PolymorphicSignature
935 @HotSpotIntrinsicCandidate
936 boolean weakCompareAndSetAcquire(Object... args);
937
938 /**
939 * Possibly atomically sets the value of a variable to the {@code newValue}
940 * with the semantics of {@link #setRelease} if the variable's current
941 * value, referred to as the <em>witness value</em>, {@code ==} the
942 * {@code expectedValue}, as accessed with the memory semantics of
943 * {@link #get}.
944 *
945 * <p>This operation may fail spuriously (typically, due to memory
946 * contention) even if the witness value does match the expected value.
947 *
948 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)boolean}.
949 *
950 * <p>The symbolic type descriptor at the call site of {@code
951 * weakCompareAndSetRelease}
952 * must match the access mode type that is the result of calling
953 * {@code accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET_RELEASE)}
954 * on this VarHandle.
955 *
956 * @param args the signature-polymorphic parameter list of the form
957 * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
958 * , statically represented using varargs.
959 * @return {@code true} if successful, otherwise {@code false} if the
960 * witness value was not the same as the {@code expectedValue} or if this
961 * operation spuriously failed.
962 * @throws UnsupportedOperationException if the access mode is unsupported
963 * for this VarHandle.
964 * @throws WrongMethodTypeException if the access mode type does not
965 * match the caller's symbolic type descriptor.
966 * @throws ClassCastException if the access mode type matches the caller's
967 * symbolic type descriptor, but a reference cast fails.
968 * @see #setRelease(Object...)
969 * @see #get(Object...)
970 */
971 public final native
972 @MethodHandle.PolymorphicSignature
973 @HotSpotIntrinsicCandidate
974 boolean weakCompareAndSetRelease(Object... args);
975
976 /**
977 * Atomically sets the value of a variable to the {@code newValue} with the
978 * memory semantics of {@link #setVolatile} and returns the variable's
979 * previous value, as accessed with the memory semantics of
980 * {@link #getVolatile}.
981 *
982 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T newValue)T}.
983 *
984 * <p>The symbolic type descriptor at the call site of {@code getAndSet}
985 * must match the access mode type that is the result of calling
986 * {@code accessModeType(VarHandle.AccessMode.GET_AND_SET)} on this
987 * VarHandle.
988 *
989 * @param args the signature-polymorphic parameter list of the form
990 * {@code (CT1 ct1, ..., CTn ctn, T newValue)}
991 * , statically represented using varargs.
992 * @return the signature-polymorphic result that is the previous value of
993 * the variable
994 * , statically represented using {@code Object}.
995 * @throws UnsupportedOperationException if the access mode is unsupported
996 * for this VarHandle.
997 * @throws WrongMethodTypeException if the access mode type does not
998 * match the caller's symbolic type descriptor.
999 * @throws ClassCastException if the access mode type matches the caller's
1000 * symbolic type descriptor, but a reference cast fails.
1001 * @see #setVolatile(Object...)
1002 * @see #getVolatile(Object...)
1003 */
1004 public final native
1005 @MethodHandle.PolymorphicSignature
1006 @HotSpotIntrinsicCandidate
1007 Object getAndSet(Object... args);
1008
1009 /**
1010 * Atomically sets the value of a variable to the {@code newValue} with the
1011 * memory semantics of {@link #set} and returns the variable's
1012 * previous value, as accessed with the memory semantics of
1013 * {@link #getAcquire}.
1014 *
1015 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T newValue)T}.
1016 *
1017 * <p>The symbolic type descriptor at the call site of {@code getAndSetAcquire}
1018 * must match the access mode type that is the result of calling
1019 * {@code accessModeType(VarHandle.AccessMode.GET_AND_SET_ACQUIRE)} on this
1020 * VarHandle.
1021 *
1022 * @param args the signature-polymorphic parameter list of the form
1023 * {@code (CT1 ct1, ..., CTn ctn, T newValue)}
1024 * , statically represented using varargs.
1025 * @return the signature-polymorphic result that is the previous value of
1026 * the variable
1027 * , statically represented using {@code Object}.
1028 * @throws UnsupportedOperationException if the access mode is unsupported
1029 * for this VarHandle.
1030 * @throws WrongMethodTypeException if the access mode type does not
1031 * match the caller's symbolic type descriptor.
1032 * @throws ClassCastException if the access mode type matches the caller's
1033 * symbolic type descriptor, but a reference cast fails.
1034 * @see #setVolatile(Object...)
1035 * @see #getVolatile(Object...)
1036 */
1037 public final native
1038 @MethodHandle.PolymorphicSignature
1039 @HotSpotIntrinsicCandidate
1040 Object getAndSetAcquire(Object... args);
1041
1042 /**
1043 * Atomically sets the value of a variable to the {@code newValue} with the
1044 * memory semantics of {@link #setRelease} and returns the variable's
1045 * previous value, as accessed with the memory semantics of
1046 * {@link #get}.
1047 *
1048 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T newValue)T}.
1049 *
1050 * <p>The symbolic type descriptor at the call site of {@code getAndSetRelease}
1051 * must match the access mode type that is the result of calling
1052 * {@code accessModeType(VarHandle.AccessMode.GET_AND_SET_RELEASE)} on this
1053 * VarHandle.
1054 *
1055 * @param args the signature-polymorphic parameter list of the form
1056 * {@code (CT1 ct1, ..., CTn ctn, T newValue)}
1057 * , statically represented using varargs.
1058 * @return the signature-polymorphic result that is the previous value of
1059 * the variable
1060 * , statically represented using {@code Object}.
1061 * @throws UnsupportedOperationException if the access mode is unsupported
1062 * for this VarHandle.
1063 * @throws WrongMethodTypeException if the access mode type does not
1064 * match the caller's symbolic type descriptor.
1065 * @throws ClassCastException if the access mode type matches the caller's
1066 * symbolic type descriptor, but a reference cast fails.
1067 * @see #setVolatile(Object...)
1068 * @see #getVolatile(Object...)
1069 */
1070 public final native
1071 @MethodHandle.PolymorphicSignature
1072 @HotSpotIntrinsicCandidate
1073 Object getAndSetRelease(Object... args);
1074
1075 // Primitive adders
1076 // Throw UnsupportedOperationException for refs
1077
1078 /**
1079 * Atomically adds the {@code value} to the current value of a variable with
1080 * the memory semantics of {@link #setVolatile}, and returns the variable's
1081 * previous value, as accessed with the memory semantics of
1082 * {@link #getVolatile}.
1083 *
1084 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T value)T}.
1085 *
1086 * <p>The symbolic type descriptor at the call site of {@code getAndAdd}
1087 * must match the access mode type that is the result of calling
1088 * {@code accessModeType(VarHandle.AccessMode.GET_AND_ADD)} on this
1089 * VarHandle.
1090 *
1091 * @param args the signature-polymorphic parameter list of the form
1092 * {@code (CT1 ct1, ..., CTn ctn, T value)}
1093 * , statically represented using varargs.
1094 * @return the signature-polymorphic result that is the previous value of
1095 * the variable
1096 * , statically represented using {@code Object}.
1097 * @throws UnsupportedOperationException if the access mode is unsupported
1098 * for this VarHandle.
1099 * @throws WrongMethodTypeException if the access mode type does not
1100 * match the caller's symbolic type descriptor.
1101 * @throws ClassCastException if the access mode type matches the caller's
1102 * symbolic type descriptor, but a reference cast fails.
1103 * @see #setVolatile(Object...)
1104 * @see #getVolatile(Object...)
1105 */
1106 public final native
1107 @MethodHandle.PolymorphicSignature
1108 @HotSpotIntrinsicCandidate
1109 Object getAndAdd(Object... args);
1110
1111 /**
1112 * Atomically adds the {@code value} to the current value of a variable with
1113 * the memory semantics of {@link #set}, and returns the variable's
1114 * previous value, as accessed with the memory semantics of
1115 * {@link #getAcquire}.
1116 *
1117 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T value)T}.
1118 *
1119 * <p>The symbolic type descriptor at the call site of {@code getAndAddAcquire}
1120 * must match the access mode type that is the result of calling
1121 * {@code accessModeType(VarHandle.AccessMode.GET_AND_ADD_ACQUIRE)} on this
1122 * VarHandle.
1123 *
1124 * @param args the signature-polymorphic parameter list of the form
1125 * {@code (CT1 ct1, ..., CTn ctn, T value)}
1126 * , statically represented using varargs.
1127 * @return the signature-polymorphic result that is the previous value of
1128 * the variable
1129 * , statically represented using {@code Object}.
1130 * @throws UnsupportedOperationException if the access mode is unsupported
1131 * for this VarHandle.
1132 * @throws WrongMethodTypeException if the access mode type does not
1133 * match the caller's symbolic type descriptor.
1134 * @throws ClassCastException if the access mode type matches the caller's
1135 * symbolic type descriptor, but a reference cast fails.
1136 * @see #setVolatile(Object...)
1137 * @see #getVolatile(Object...)
1138 */
1139 public final native
1140 @MethodHandle.PolymorphicSignature
1141 @HotSpotIntrinsicCandidate
1142 Object getAndAddAcquire(Object... args);
1143
1144 /**
1145 * Atomically adds the {@code value} to the current value of a variable with
1146 * the memory semantics of {@link #setRelease}, and returns the variable's
1147 * previous value, as accessed with the memory semantics of
1148 * {@link #get}.
1149 *
1150 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T value)T}.
1151 *
1152 * <p>The symbolic type descriptor at the call site of {@code getAndAddRelease}
1153 * must match the access mode type that is the result of calling
1154 * {@code accessModeType(VarHandle.AccessMode.GET_AND_ADD_RELEASE)} on this
1155 * VarHandle.
1156 *
1157 * @param args the signature-polymorphic parameter list of the form
1158 * {@code (CT1 ct1, ..., CTn ctn, T value)}
1159 * , statically represented using varargs.
1160 * @return the signature-polymorphic result that is the previous value of
1161 * the variable
1162 * , statically represented using {@code Object}.
1163 * @throws UnsupportedOperationException if the access mode is unsupported
1164 * for this VarHandle.
1165 * @throws WrongMethodTypeException if the access mode type does not
1166 * match the caller's symbolic type descriptor.
1167 * @throws ClassCastException if the access mode type matches the caller's
1168 * symbolic type descriptor, but a reference cast fails.
1169 * @see #setVolatile(Object...)
1170 * @see #getVolatile(Object...)
1171 */
1172 public final native
1173 @MethodHandle.PolymorphicSignature
1174 @HotSpotIntrinsicCandidate
1175 Object getAndAddRelease(Object... args);
1176
1177
1178 // Bitwise operations
1179 // Throw UnsupportedOperationException for refs
1180
1181 /**
1182 * Atomically sets the value of a variable to the result of
1183 * bitwise OR between the variable's current value and the {@code mask}
1184 * with the memory semantics of {@link #setVolatile} and returns the
1185 * variable's previous value, as accessed with the memory semantics of
1186 * {@link #getVolatile}.
1187 *
1188 * <p>If the variable type is the non-integral {@code boolean} type then a
1189 * logical OR is performed instead of a bitwise OR.
1190 *
1191 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T mask)T}.
1192 *
1193 * <p>The symbolic type descriptor at the call site of {@code getAndBitwiseOr}
1194 * must match the access mode type that is the result of calling
1195 * {@code accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_OR)} on this
1196 * VarHandle.
1197 *
1198 * @param args the signature-polymorphic parameter list of the form
1199 * {@code (CT1 ct1, ..., CTn ctn, T mask)}
1200 * , statically represented using varargs.
1201 * @return the signature-polymorphic result that is the previous value of
1202 * the variable
1203 * , statically represented using {@code Object}.
1204 * @throws UnsupportedOperationException if the access mode is unsupported
1205 * for this VarHandle.
1206 * @throws WrongMethodTypeException if the access mode type does not
1207 * match the caller's symbolic type descriptor.
1208 * @throws ClassCastException if the access mode type matches the caller's
1209 * symbolic type descriptor, but a reference cast fails.
1210 * @see #setVolatile(Object...)
1211 * @see #getVolatile(Object...)
1212 */
1213 public final native
1214 @MethodHandle.PolymorphicSignature
1215 @HotSpotIntrinsicCandidate
1216 Object getAndBitwiseOr(Object... args);
1217
1218 /**
1219 * Atomically sets the value of a variable to the result of
1220 * bitwise OR between the variable's current value and the {@code mask}
1221 * with the memory semantics of {@link #set} and returns the
1222 * variable's previous value, as accessed with the memory semantics of
1223 * {@link #getAcquire}.
1224 *
1225 * <p>If the variable type is the non-integral {@code boolean} type then a
1226 * logical OR is performed instead of a bitwise OR.
1227 *
1228 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T mask)T}.
1229 *
1230 * <p>The symbolic type descriptor at the call site of {@code getAndBitwiseOrAcquire}
1231 * must match the access mode type that is the result of calling
1232 * {@code accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_OR_ACQUIRE)} on this
1233 * VarHandle.
1234 *
1235 * @param args the signature-polymorphic parameter list of the form
1236 * {@code (CT1 ct1, ..., CTn ctn, T mask)}
1237 * , statically represented using varargs.
1238 * @return the signature-polymorphic result that is the previous value of
1239 * the variable
1240 * , statically represented using {@code Object}.
1241 * @throws UnsupportedOperationException if the access mode is unsupported
1242 * for this VarHandle.
1243 * @throws WrongMethodTypeException if the access mode type does not
1244 * match the caller's symbolic type descriptor.
1245 * @throws ClassCastException if the access mode type matches the caller's
1246 * symbolic type descriptor, but a reference cast fails.
1247 * @see #set(Object...)
1248 * @see #getAcquire(Object...)
1249 */
1250 public final native
1251 @MethodHandle.PolymorphicSignature
1252 @HotSpotIntrinsicCandidate
1253 Object getAndBitwiseOrAcquire(Object... args);
1254
1255 /**
1256 * Atomically sets the value of a variable to the result of
1257 * bitwise OR between the variable's current value and the {@code mask}
1258 * with the memory semantics of {@link #setRelease} and returns the
1259 * variable's previous value, as accessed with the memory semantics of
1260 * {@link #get}.
1261 *
1262 * <p>If the variable type is the non-integral {@code boolean} type then a
1263 * logical OR is performed instead of a bitwise OR.
1264 *
1265 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T mask)T}.
1266 *
1267 * <p>The symbolic type descriptor at the call site of {@code getAndBitwiseOrRelease}
1268 * must match the access mode type that is the result of calling
1269 * {@code accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_OR_RELEASE)} on this
1270 * VarHandle.
1271 *
1272 * @param args the signature-polymorphic parameter list of the form
1273 * {@code (CT1 ct1, ..., CTn ctn, T mask)}
1274 * , statically represented using varargs.
1275 * @return the signature-polymorphic result that is the previous value of
1276 * the variable
1277 * , statically represented using {@code Object}.
1278 * @throws UnsupportedOperationException if the access mode is unsupported
1279 * for this VarHandle.
1280 * @throws WrongMethodTypeException if the access mode type does not
1281 * match the caller's symbolic type descriptor.
1282 * @throws ClassCastException if the access mode type matches the caller's
1283 * symbolic type descriptor, but a reference cast fails.
1284 * @see #setRelease(Object...)
1285 * @see #get(Object...)
1286 */
1287 public final native
1288 @MethodHandle.PolymorphicSignature
1289 @HotSpotIntrinsicCandidate
1290 Object getAndBitwiseOrRelease(Object... args);
1291
1292 /**
1293 * Atomically sets the value of a variable to the result of
1294 * bitwise AND between the variable's current value and the {@code mask}
1295 * with the memory semantics of {@link #setVolatile} and returns the
1296 * variable's previous value, as accessed with the memory semantics of
1297 * {@link #getVolatile}.
1298 *
1299 * <p>If the variable type is the non-integral {@code boolean} type then a
1300 * logical AND is performed instead of a bitwise AND.
1301 *
1302 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T mask)T}.
1303 *
1304 * <p>The symbolic type descriptor at the call site of {@code getAndBitwiseAnd}
1305 * must match the access mode type that is the result of calling
1306 * {@code accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_AND)} on this
1307 * VarHandle.
1308 *
1309 * @param args the signature-polymorphic parameter list of the form
1310 * {@code (CT1 ct1, ..., CTn ctn, T mask)}
1311 * , statically represented using varargs.
1312 * @return the signature-polymorphic result that is the previous value of
1313 * the variable
1314 * , statically represented using {@code Object}.
1315 * @throws UnsupportedOperationException if the access mode is unsupported
1316 * for this VarHandle.
1317 * @throws WrongMethodTypeException if the access mode type does not
1318 * match the caller's symbolic type descriptor.
1319 * @throws ClassCastException if the access mode type matches the caller's
1320 * symbolic type descriptor, but a reference cast fails.
1321 * @see #setVolatile(Object...)
1322 * @see #getVolatile(Object...)
1323 */
1324 public final native
1325 @MethodHandle.PolymorphicSignature
1326 @HotSpotIntrinsicCandidate
1327 Object getAndBitwiseAnd(Object... args);
1328
1329 /**
1330 * Atomically sets the value of a variable to the result of
1331 * bitwise AND between the variable's current value and the {@code mask}
1332 * with the memory semantics of {@link #set} and returns the
1333 * variable's previous value, as accessed with the memory semantics of
1334 * {@link #getAcquire}.
1335 *
1336 * <p>If the variable type is the non-integral {@code boolean} type then a
1337 * logical AND is performed instead of a bitwise AND.
1338 *
1339 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T mask)T}.
1340 *
1341 * <p>The symbolic type descriptor at the call site of {@code getAndBitwiseAndAcquire}
1342 * must match the access mode type that is the result of calling
1343 * {@code accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_AND_ACQUIRE)} on this
1344 * VarHandle.
1345 *
1346 * @param args the signature-polymorphic parameter list of the form
1347 * {@code (CT1 ct1, ..., CTn ctn, T mask)}
1348 * , statically represented using varargs.
1349 * @return the signature-polymorphic result that is the previous value of
1350 * the variable
1351 * , statically represented using {@code Object}.
1352 * @throws UnsupportedOperationException if the access mode is unsupported
1353 * for this VarHandle.
1354 * @throws WrongMethodTypeException if the access mode type does not
1355 * match the caller's symbolic type descriptor.
1356 * @throws ClassCastException if the access mode type matches the caller's
1357 * symbolic type descriptor, but a reference cast fails.
1358 * @see #set(Object...)
1359 * @see #getAcquire(Object...)
1360 */
1361 public final native
1362 @MethodHandle.PolymorphicSignature
1363 @HotSpotIntrinsicCandidate
1364 Object getAndBitwiseAndAcquire(Object... args);
1365
1366 /**
1367 * Atomically sets the value of a variable to the result of
1368 * bitwise AND between the variable's current value and the {@code mask}
1369 * with the memory semantics of {@link #setRelease} and returns the
1370 * variable's previous value, as accessed with the memory semantics of
1371 * {@link #get}.
1372 *
1373 * <p>If the variable type is the non-integral {@code boolean} type then a
1374 * logical AND is performed instead of a bitwise AND.
1375 *
1376 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T mask)T}.
1377 *
1378 * <p>The symbolic type descriptor at the call site of {@code getAndBitwiseAndRelease}
1379 * must match the access mode type that is the result of calling
1380 * {@code accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_AND_RELEASE)} on this
1381 * VarHandle.
1382 *
1383 * @param args the signature-polymorphic parameter list of the form
1384 * {@code (CT1 ct1, ..., CTn ctn, T mask)}
1385 * , statically represented using varargs.
1386 * @return the signature-polymorphic result that is the previous value of
1387 * the variable
1388 * , statically represented using {@code Object}.
1389 * @throws UnsupportedOperationException if the access mode is unsupported
1390 * for this VarHandle.
1391 * @throws WrongMethodTypeException if the access mode type does not
1392 * match the caller's symbolic type descriptor.
1393 * @throws ClassCastException if the access mode type matches the caller's
1394 * symbolic type descriptor, but a reference cast fails.
1395 * @see #setRelease(Object...)
1396 * @see #get(Object...)
1397 */
1398 public final native
1399 @MethodHandle.PolymorphicSignature
1400 @HotSpotIntrinsicCandidate
1401 Object getAndBitwiseAndRelease(Object... args);
1402
1403 /**
1404 * Atomically sets the value of a variable to the result of
1405 * bitwise XOR between the variable's current value and the {@code mask}
1406 * with the memory semantics of {@link #setVolatile} and returns the
1407 * variable's previous value, as accessed with the memory semantics of
1408 * {@link #getVolatile}.
1409 *
1410 * <p>If the variable type is the non-integral {@code boolean} type then a
1411 * logical XOR is performed instead of a bitwise XOR.
1412 *
1413 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T mask)T}.
1414 *
1415 * <p>The symbolic type descriptor at the call site of {@code getAndBitwiseXor}
1416 * must match the access mode type that is the result of calling
1417 * {@code accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_XOR)} on this
1418 * VarHandle.
1419 *
1420 * @param args the signature-polymorphic parameter list of the form
1421 * {@code (CT1 ct1, ..., CTn ctn, T mask)}
1422 * , statically represented using varargs.
1423 * @return the signature-polymorphic result that is the previous value of
1424 * the variable
1425 * , statically represented using {@code Object}.
1426 * @throws UnsupportedOperationException if the access mode is unsupported
1427 * for this VarHandle.
1428 * @throws WrongMethodTypeException if the access mode type does not
1429 * match the caller's symbolic type descriptor.
1430 * @throws ClassCastException if the access mode type matches the caller's
1431 * symbolic type descriptor, but a reference cast fails.
1432 * @see #setVolatile(Object...)
1433 * @see #getVolatile(Object...)
1434 */
1435 public final native
1436 @MethodHandle.PolymorphicSignature
1437 @HotSpotIntrinsicCandidate
1438 Object getAndBitwiseXor(Object... args);
1439
1440 /**
1441 * Atomically sets the value of a variable to the result of
1442 * bitwise XOR between the variable's current value and the {@code mask}
1443 * with the memory semantics of {@link #set} and returns the
1444 * variable's previous value, as accessed with the memory semantics of
1445 * {@link #getAcquire}.
1446 *
1447 * <p>If the variable type is the non-integral {@code boolean} type then a
1448 * logical XOR is performed instead of a bitwise XOR.
1449 *
1450 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T mask)T}.
1451 *
1452 * <p>The symbolic type descriptor at the call site of {@code getAndBitwiseXorAcquire}
1453 * must match the access mode type that is the result of calling
1454 * {@code accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_XOR_ACQUIRE)} on this
1455 * VarHandle.
1456 *
1457 * @param args the signature-polymorphic parameter list of the form
1458 * {@code (CT1 ct1, ..., CTn ctn, T mask)}
1459 * , statically represented using varargs.
1460 * @return the signature-polymorphic result that is the previous value of
1461 * the variable
1462 * , statically represented using {@code Object}.
1463 * @throws UnsupportedOperationException if the access mode is unsupported
1464 * for this VarHandle.
1465 * @throws WrongMethodTypeException if the access mode type does not
1466 * match the caller's symbolic type descriptor.
1467 * @throws ClassCastException if the access mode type matches the caller's
1468 * symbolic type descriptor, but a reference cast fails.
1469 * @see #set(Object...)
1470 * @see #getAcquire(Object...)
1471 */
1472 public final native
1473 @MethodHandle.PolymorphicSignature
1474 @HotSpotIntrinsicCandidate
1475 Object getAndBitwiseXorAcquire(Object... args);
1476
1477 /**
1478 * Atomically sets the value of a variable to the result of
1479 * bitwise XOR between the variable's current value and the {@code mask}
1480 * with the memory semantics of {@link #setRelease} and returns the
1481 * variable's previous value, as accessed with the memory semantics of
1482 * {@link #get}.
1483 *
1484 * <p>If the variable type is the non-integral {@code boolean} type then a
1485 * logical XOR is performed instead of a bitwise XOR.
1486 *
1487 * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T mask)T}.
1488 *
1489 * <p>The symbolic type descriptor at the call site of {@code getAndBitwiseXorRelease}
1490 * must match the access mode type that is the result of calling
1491 * {@code accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_XOR_RELEASE)} on this
1492 * VarHandle.
1493 *
1494 * @param args the signature-polymorphic parameter list of the form
1495 * {@code (CT1 ct1, ..., CTn ctn, T mask)}
1496 * , statically represented using varargs.
1497 * @return the signature-polymorphic result that is the previous value of
1498 * the variable
1499 * , statically represented using {@code Object}.
1500 * @throws UnsupportedOperationException if the access mode is unsupported
1501 * for this VarHandle.
1502 * @throws WrongMethodTypeException if the access mode type does not
1503 * match the caller's symbolic type descriptor.
1504 * @throws ClassCastException if the access mode type matches the caller's
1505 * symbolic type descriptor, but a reference cast fails.
1506 * @see #setRelease(Object...)
1507 * @see #get(Object...)
1508 */
1509 public final native
1510 @MethodHandle.PolymorphicSignature
1511 @HotSpotIntrinsicCandidate
1512 Object getAndBitwiseXorRelease(Object... args);
1513
1514
1515 enum AccessType {
1516 GET(Object.class),
1517 SET(void.class),
1518 COMPARE_AND_SWAP(boolean.class),
1519 COMPARE_AND_EXCHANGE(Object.class),
1520 GET_AND_UPDATE(Object.class);
1521
1522 final Class<?> returnType;
1523 final boolean isMonomorphicInReturnType;
1524
1525 AccessType(Class<?> returnType) {
1526 this.returnType = returnType;
1527 isMonomorphicInReturnType = returnType != Object.class;
1528 }
1529
1530 MethodType accessModeType(Class<?> receiver, Class<?> value,
1531 Class<?>... intermediate) {
1532 Class<?>[] ps;
1533 int i;
1534 switch (this) {
1535 case GET:
1536 ps = allocateParameters(0, receiver, intermediate);
1537 fillParameters(ps, receiver, intermediate);
1538 return MethodType.methodType(value, ps);
1539 case SET:
1540 ps = allocateParameters(1, receiver, intermediate);
1541 i = fillParameters(ps, receiver, intermediate);
1542 ps[i] = value;
1543 return MethodType.methodType(void.class, ps);
1544 case COMPARE_AND_SWAP:
1545 ps = allocateParameters(2, receiver, intermediate);
1546 i = fillParameters(ps, receiver, intermediate);
1547 ps[i++] = value;
1548 ps[i] = value;
1549 return MethodType.methodType(boolean.class, ps);
1550 case COMPARE_AND_EXCHANGE:
1551 ps = allocateParameters(2, receiver, intermediate);
1552 i = fillParameters(ps, receiver, intermediate);
1553 ps[i++] = value;
1554 ps[i] = value;
1555 return MethodType.methodType(value, ps);
1556 case GET_AND_UPDATE:
1557 ps = allocateParameters(1, receiver, intermediate);
1558 i = fillParameters(ps, receiver, intermediate);
1559 ps[i] = value;
1560 return MethodType.methodType(value, ps);
1561 default:
1562 throw new InternalError("Unknown AccessType");
1563 }
1564 }
1565
1566 private static Class<?>[] allocateParameters(int values,
1567 Class<?> receiver, Class<?>... intermediate) {
1568 int size = ((receiver != null) ? 1 : 0) + intermediate.length + values;
1569 return new Class<?>[size];
1570 }
1571
1572 private static int fillParameters(Class<?>[] ps,
1573 Class<?> receiver, Class<?>... intermediate) {
1574 int i = 0;
1575 if (receiver != null)
1576 ps[i++] = receiver;
1577 for (int j = 0; j < intermediate.length; j++)
1578 ps[i++] = intermediate[j];
1579 return i;
1580 }
1581 }
1582
1583 /**
1584 * The set of access modes that specify how a variable, referenced by a
1585 * VarHandle, is accessed.
1586 */
1587 public enum AccessMode {
1588 /**
1589 * The access mode whose access is specified by the corresponding
1590 * method
1591 * {@link VarHandle#get VarHandle.get}
1592 */
1593 GET("get", AccessType.GET),
1594 /**
1595 * The access mode whose access is specified by the corresponding
1596 * method
1597 * {@link VarHandle#set VarHandle.set}
1598 */
1599 SET("set", AccessType.SET),
1600 /**
1601 * The access mode whose access is specified by the corresponding
1602 * method
1603 * {@link VarHandle#getVolatile VarHandle.getVolatile}
1604 */
1605 GET_VOLATILE("getVolatile", AccessType.GET),
1606 /**
1607 * The access mode whose access is specified by the corresponding
1608 * method
1609 * {@link VarHandle#setVolatile VarHandle.setVolatile}
1610 */
1611 SET_VOLATILE("setVolatile", AccessType.SET),
1612 /**
1613 * The access mode whose access is specified by the corresponding
1614 * method
1615 * {@link VarHandle#getAcquire VarHandle.getAcquire}
1616 */
1617 GET_ACQUIRE("getAcquire", AccessType.GET),
1618 /**
1619 * The access mode whose access is specified by the corresponding
1620 * method
1621 * {@link VarHandle#setRelease VarHandle.setRelease}
1622 */
1623 SET_RELEASE("setRelease", AccessType.SET),
1624 /**
1625 * The access mode whose access is specified by the corresponding
1626 * method
1627 * {@link VarHandle#getOpaque VarHandle.getOpaque}
1628 */
1629 GET_OPAQUE("getOpaque", AccessType.GET),
1630 /**
1631 * The access mode whose access is specified by the corresponding
1632 * method
1633 * {@link VarHandle#setOpaque VarHandle.setOpaque}
1634 */
1635 SET_OPAQUE("setOpaque", AccessType.SET),
1636 /**
1637 * The access mode whose access is specified by the corresponding
1638 * method
1639 * {@link VarHandle#compareAndSet VarHandle.compareAndSet}
1640 */
1641 COMPARE_AND_SET("compareAndSet", AccessType.COMPARE_AND_SWAP),
1642 /**
1643 * The access mode whose access is specified by the corresponding
1644 * method
1645 * {@link VarHandle#compareAndExchange VarHandle.compareAndExchange}
1646 */
1647 COMPARE_AND_EXCHANGE("compareAndExchange", AccessType.COMPARE_AND_EXCHANGE),
1648 /**
1649 * The access mode whose access is specified by the corresponding
1650 * method
1651 * {@link VarHandle#compareAndExchangeAcquire VarHandle.compareAndExchangeAcquire}
1652 */
1653 COMPARE_AND_EXCHANGE_ACQUIRE("compareAndExchangeAcquire", AccessType.COMPARE_AND_EXCHANGE),
1654 /**
1655 * The access mode whose access is specified by the corresponding
1656 * method
1657 * {@link VarHandle#compareAndExchangeRelease VarHandle.compareAndExchangeRelease}
1658 */
1659 COMPARE_AND_EXCHANGE_RELEASE("compareAndExchangeRelease", AccessType.COMPARE_AND_EXCHANGE),
1660 /**
1661 * The access mode whose access is specified by the corresponding
1662 * method
1663 * {@link VarHandle#weakCompareAndSetPlain VarHandle.weakCompareAndSetPlain}
1664 */
1665 WEAK_COMPARE_AND_SET_PLAIN("weakCompareAndSetPlain", AccessType.COMPARE_AND_SWAP),
1666 /**
1667 * The access mode whose access is specified by the corresponding
1668 * method
1669 * {@link VarHandle#weakCompareAndSet VarHandle.weakCompareAndSet}
1670 */
1671 WEAK_COMPARE_AND_SET("weakCompareAndSet", AccessType.COMPARE_AND_SWAP),
1672 /**
1673 * The access mode whose access is specified by the corresponding
1674 * method
1675 * {@link VarHandle#weakCompareAndSetAcquire VarHandle.weakCompareAndSetAcquire}
1676 */
1677 WEAK_COMPARE_AND_SET_ACQUIRE("weakCompareAndSetAcquire", AccessType.COMPARE_AND_SWAP),
1678 /**
1679 * The access mode whose access is specified by the corresponding
1680 * method
1681 * {@link VarHandle#weakCompareAndSetRelease VarHandle.weakCompareAndSetRelease}
1682 */
1683 WEAK_COMPARE_AND_SET_RELEASE("weakCompareAndSetRelease", AccessType.COMPARE_AND_SWAP),
1684 /**
1685 * The access mode whose access is specified by the corresponding
1686 * method
1687 * {@link VarHandle#getAndSet VarHandle.getAndSet}
1688 */
1689 GET_AND_SET("getAndSet", AccessType.GET_AND_UPDATE),
1690 /**
1691 * The access mode whose access is specified by the corresponding
1692 * method
1693 * {@link VarHandle#getAndSetAcquire VarHandle.getAndSetAcquire}
1694 */
1695 GET_AND_SET_ACQUIRE("getAndSetAcquire", AccessType.GET_AND_UPDATE),
1696 /**
1697 * The access mode whose access is specified by the corresponding
1698 * method
1699 * {@link VarHandle#getAndSetRelease VarHandle.getAndSetRelease}
1700 */
1701 GET_AND_SET_RELEASE("getAndSetRelease", AccessType.GET_AND_UPDATE),
1702 /**
1703 * The access mode whose access is specified by the corresponding
1704 * method
1705 * {@link VarHandle#getAndAdd VarHandle.getAndAdd}
1706 */
1707 GET_AND_ADD("getAndAdd", AccessType.GET_AND_UPDATE),
1708 /**
1709 * The access mode whose access is specified by the corresponding
1710 * method
1711 * {@link VarHandle#getAndAddAcquire VarHandle.getAndAddAcquire}
1712 */
1713 GET_AND_ADD_ACQUIRE("getAndAddAcquire", AccessType.GET_AND_UPDATE),
1714 /**
1715 * The access mode whose access is specified by the corresponding
1716 * method
1717 * {@link VarHandle#getAndAddRelease VarHandle.getAndAddRelease}
1718 */
1719 GET_AND_ADD_RELEASE("getAndAddRelease", AccessType.GET_AND_UPDATE),
1720 /**
1721 * The access mode whose access is specified by the corresponding
1722 * method
1723 * {@link VarHandle#getAndBitwiseOr VarHandle.getAndBitwiseOr}
1724 */
1725 GET_AND_BITWISE_OR("getAndBitwiseOr", AccessType.GET_AND_UPDATE),
1726 /**
1727 * The access mode whose access is specified by the corresponding
1728 * method
1729 * {@link VarHandle#getAndBitwiseOrRelease VarHandle.getAndBitwiseOrRelease}
1730 */
1731 GET_AND_BITWISE_OR_RELEASE("getAndBitwiseOrRelease", AccessType.GET_AND_UPDATE),
1732 /**
1733 * The access mode whose access is specified by the corresponding
1734 * method
1735 * {@link VarHandle#getAndBitwiseOrAcquire VarHandle.getAndBitwiseOrAcquire}
1736 */
1737 GET_AND_BITWISE_OR_ACQUIRE("getAndBitwiseOrAcquire", AccessType.GET_AND_UPDATE),
1738 /**
1739 * The access mode whose access is specified by the corresponding
1740 * method
1741 * {@link VarHandle#getAndBitwiseAnd VarHandle.getAndBitwiseAnd}
1742 */
1743 GET_AND_BITWISE_AND("getAndBitwiseAnd", AccessType.GET_AND_UPDATE),
1744 /**
1745 * The access mode whose access is specified by the corresponding
1746 * method
1747 * {@link VarHandle#getAndBitwiseAndRelease VarHandle.getAndBitwiseAndRelease}
1748 */
1749 GET_AND_BITWISE_AND_RELEASE("getAndBitwiseAndRelease", AccessType.GET_AND_UPDATE),
1750 /**
1751 * The access mode whose access is specified by the corresponding
1752 * method
1753 * {@link VarHandle#getAndBitwiseAndAcquire VarHandle.getAndBitwiseAndAcquire}
1754 */
1755 GET_AND_BITWISE_AND_ACQUIRE("getAndBitwiseAndAcquire", AccessType.GET_AND_UPDATE),
1756 /**
1757 * The access mode whose access is specified by the corresponding
1758 * method
1759 * {@link VarHandle#getAndBitwiseXor VarHandle.getAndBitwiseXor}
1760 */
1761 GET_AND_BITWISE_XOR("getAndBitwiseXor", AccessType.GET_AND_UPDATE),
1762 /**
1763 * The access mode whose access is specified by the corresponding
1764 * method
1765 * {@link VarHandle#getAndBitwiseXorRelease VarHandle.getAndBitwiseXorRelease}
1766 */
1767 GET_AND_BITWISE_XOR_RELEASE("getAndBitwiseXorRelease", AccessType.GET_AND_UPDATE),
1768 /**
1769 * The access mode whose access is specified by the corresponding
1770 * method
1771 * {@link VarHandle#getAndBitwiseXorAcquire VarHandle.getAndBitwiseXorAcquire}
1772 */
1773 GET_AND_BITWISE_XOR_ACQUIRE("getAndBitwiseXorAcquire", AccessType.GET_AND_UPDATE),
1774 ;
1775
1776 static final Map<String, AccessMode> methodNameToAccessMode;
1777 static {
1778 // Initial capacity of # values is sufficient to avoid resizes
1779 // for the smallest table size (32)
1780 methodNameToAccessMode = new HashMap<>(AccessMode.values().length);
1781 for (AccessMode am : AccessMode.values()) {
1782 methodNameToAccessMode.put(am.methodName, am);
1783 }
1784 }
1785
1786 final String methodName;
1787 final AccessType at;
1788
1789 AccessMode(final String methodName, AccessType at) {
1790 this.methodName = methodName;
1791 this.at = at;
1792 }
1793
1794 /**
1795 * Returns the {@code VarHandle} signature-polymorphic method name
1796 * associated with this {@code AccessMode} value.
1797 *
1798 * @return the signature-polymorphic method name
1799 * @see #valueFromMethodName
1800 */
1801 public String methodName() {
1802 return methodName;
1803 }
1804
1805 /**
1806 * Returns the {@code AccessMode} value associated with the specified
1807 * {@code VarHandle} signature-polymorphic method name.
1808 *
1809 * @param methodName the signature-polymorphic method name
1810 * @return the {@code AccessMode} value
1811 * @throws IllegalArgumentException if there is no {@code AccessMode}
1812 * value associated with method name (indicating the method
1813 * name does not correspond to a {@code VarHandle}
1814 * signature-polymorphic method name).
1815 * @see #methodName
1816 */
1817 public static AccessMode valueFromMethodName(String methodName) {
1818 AccessMode am = methodNameToAccessMode.get(methodName);
1819 if (am != null) return am;
1820 throw new IllegalArgumentException("No AccessMode value for method name " + methodName);
1821 }
1822
1823 @ForceInline
1824 static MemberName getMemberName(int ordinal, VarForm vform) {
1825 return vform.memberName_table[ordinal];
1826 }
1827 }
1828
1829 static final class AccessDescriptor {
1830 final MethodType symbolicMethodTypeErased;
1831 final MethodType symbolicMethodTypeInvoker;
1832 final Class<?> returnType;
1833 final int type;
1834 final int mode;
1835
1836 public AccessDescriptor(MethodType symbolicMethodType, int type, int mode) {
1837 this.symbolicMethodTypeErased = symbolicMethodType.erase();
1838 this.symbolicMethodTypeInvoker = symbolicMethodType.insertParameterTypes(0, VarHandle.class);
1839 this.returnType = symbolicMethodType.returnType();
1840 this.type = type;
1841 this.mode = mode;
1842 }
1843 }
1844
1845 /**
1846 * Returns the variable type of variables referenced by this VarHandle.
1847 *
1848 * @return the variable type of variables referenced by this VarHandle
1849 */
1850 public final Class<?> varType() {
1851 MethodType typeSet = accessModeType(AccessMode.SET);
1852 return typeSet.parameterType(typeSet.parameterCount() - 1);
1853 }
1854
1855 /**
1856 * Returns the coordinate types for this VarHandle.
1857 *
1858 * @return the coordinate types for this VarHandle. The returned
1859 * list is unmodifiable
1860 */
1861 public final List<Class<?>> coordinateTypes() {
1862 MethodType typeGet = accessModeType(AccessMode.GET);
1863 return typeGet.parameterList();
1864 }
1865
1866 /**
1867 * Obtains the access mode type for this VarHandle and a given access mode.
1868 *
1869 * <p>The access mode type's parameter types will consist of a prefix that
1870 * is the coordinate types of this VarHandle followed by further
1871 * types as defined by the access mode method.
1872 * The access mode type's return type is defined by the return type of the
1873 * access mode method.
1874 *
1875 * @param accessMode the access mode, corresponding to the
1876 * signature-polymorphic method of the same name
1877 * @return the access mode type for the given access mode
1878 */
1879 public final MethodType accessModeType(AccessMode accessMode) {
1880 TypesAndInvokers tis = getTypesAndInvokers();
1881 MethodType mt = tis.methodType_table[accessMode.at.ordinal()];
1882 if (mt == null) {
1883 mt = tis.methodType_table[accessMode.at.ordinal()] =
1884 accessModeTypeUncached(accessMode);
1885 }
1886 return mt;
1887 }
1888 abstract MethodType accessModeTypeUncached(AccessMode accessMode);
1889
1890 /**
1891 * Returns {@code true} if the given access mode is supported, otherwise
1892 * {@code false}.
1893 *
1894 * <p>The return of a {@code false} value for a given access mode indicates
1895 * that an {@code UnsupportedOperationException} is thrown on invocation
1896 * of the corresponding access mode method.
1897 *
1898 * @param accessMode the access mode, corresponding to the
1899 * signature-polymorphic method of the same name
1900 * @return {@code true} if the given access mode is supported, otherwise
1901 * {@code false}.
1902 */
1903 public final boolean isAccessModeSupported(AccessMode accessMode) {
1904 return AccessMode.getMemberName(accessMode.ordinal(), vform) != null;
1905 }
1906
1907 /**
1908 * Obtains a method handle bound to this VarHandle and the given access
1909 * mode.
1910 *
1911 * @apiNote This method, for a VarHandle {@code vh} and access mode
1912 * {@code {access-mode}}, returns a method handle that is equivalent to
1913 * method handle {@code bmh} in the following code (though it may be more
1914 * efficient):
1915 * <pre>{@code
1916 * MethodHandle mh = MethodHandles.varHandleExactInvoker(
1917 * vh.accessModeType(VarHandle.AccessMode.{access-mode}));
1918 *
1919 * MethodHandle bmh = mh.bindTo(vh);
1920 * }</pre>
1921 *
1922 * @param accessMode the access mode, corresponding to the
1923 * signature-polymorphic method of the same name
1924 * @return a method handle bound to this VarHandle and the given access mode
1925 */
1926 public final MethodHandle toMethodHandle(AccessMode accessMode) {
1927 MemberName mn = AccessMode.getMemberName(accessMode.ordinal(), vform);
1928 if (mn != null) {
1929 MethodHandle mh = getMethodHandle(accessMode.ordinal());
1930 return mh.bindTo(this);
1931 }
1932 else {
1933 // Ensure an UnsupportedOperationException is thrown
1934 return MethodHandles.varHandleInvoker(accessMode, accessModeType(accessMode)).
1935 bindTo(this);
1936 }
1937 }
1938
1939 @Stable
1940 TypesAndInvokers typesAndInvokers;
1941
1942 static class TypesAndInvokers {
1943 final @Stable
1944 MethodType[] methodType_table =
1945 new MethodType[VarHandle.AccessType.values().length];
1946
1947 final @Stable
1948 MethodHandle[] methodHandle_table =
1949 new MethodHandle[AccessMode.values().length];
1950 }
1951
1952 @ForceInline
1953 private final TypesAndInvokers getTypesAndInvokers() {
1954 TypesAndInvokers tis = typesAndInvokers;
1955 if (tis == null) {
1956 tis = typesAndInvokers = new TypesAndInvokers();
1957 }
1958 return tis;
1959 }
1960
1961 @ForceInline
1962 final MethodHandle getMethodHandle(int mode) {
1963 TypesAndInvokers tis = getTypesAndInvokers();
1964 MethodHandle mh = tis.methodHandle_table[mode];
1965 if (mh == null) {
1966 mh = tis.methodHandle_table[mode] = getMethodHandleUncached(mode);
1967 }
1968 return mh;
1969 }
1970 private final MethodHandle getMethodHandleUncached(int mode) {
1971 MethodType mt = accessModeType(AccessMode.values()[mode]).
1972 insertParameterTypes(0, VarHandle.class);
1973 MemberName mn = vform.getMemberName(mode);
1974 DirectMethodHandle dmh = DirectMethodHandle.make(mn);
1975 // Such a method handle must not be publically exposed directly
1976 // otherwise it can be cracked, it must be transformed or rebound
1977 // before exposure
1978 MethodHandle mh = dmh.copyWith(mt, dmh.form);
1979 assert mh.type().erase() == mn.getMethodType().erase();
1980 return mh;
1981 }
1982
1983
1984 /*non-public*/
1985 final void updateVarForm(VarForm newVForm) {
1986 if (vform == newVForm) return;
1987 UNSAFE.putObject(this, VFORM_OFFSET, newVForm);
1988 UNSAFE.fullFence();
1989 }
1990
1991 static final BiFunction<String, List<Integer>, ArrayIndexOutOfBoundsException>
1992 AIOOBE_SUPPLIER = Preconditions.outOfBoundsExceptionFormatter(
1993 new Function<String, ArrayIndexOutOfBoundsException>() {
1994 @Override
1995 public ArrayIndexOutOfBoundsException apply(String s) {
1996 return new ArrayIndexOutOfBoundsException(s);
1997 }
1998 });
1999
2000 private static final long VFORM_OFFSET;
2001
2002 static {
2003 VFORM_OFFSET = UNSAFE.objectFieldOffset(VarHandle.class, "vform");
2004
2005 // The VarHandleGuards must be initialized to ensure correct
2006 // compilation of the guard methods
2007 UNSAFE.ensureClassInitialized(VarHandleGuards.class);
2008 }
2009
2010
2011 // Fence methods
2012
2013 /**
2014 * Ensures that loads and stores before the fence will not be reordered
2015 * with
2016 * loads and stores after the fence.
2017 *
2018 * @apiNote Ignoring the many semantic differences from C and C++, this
2019 * method has memory ordering effects compatible with
2020 * {@code atomic_thread_fence(memory_order_seq_cst)}
2021 */
2022 @ForceInline
2023 public static void fullFence() {
2024 UNSAFE.fullFence();
2025 }
2026
2027 /**
2028 * Ensures that loads before the fence will not be reordered with loads and
2029 * stores after the fence.
2030 *
2031 * @apiNote Ignoring the many semantic differences from C and C++, this
2032 * method has memory ordering effects compatible with
2033 * {@code atomic_thread_fence(memory_order_acquire)}
2034 */
2035 @ForceInline
2036 public static void acquireFence() {
2037 UNSAFE.loadFence();
2038 }
2039
2040 /**
2041 * Ensures that loads and stores before the fence will not be
2042 * reordered with stores after the fence.
2043 *
2044 * @apiNote Ignoring the many semantic differences from C and C++, this
2045 * method has memory ordering effects compatible with
2046 * {@code atomic_thread_fence(memory_order_release)}
2047 */
2048 @ForceInline
2049 public static void releaseFence() {
2050 UNSAFE.storeFence();
2051 }
2052
2053 /**
2054 * Ensures that loads before the fence will not be reordered with
2055 * loads after the fence.
2056 */
2057 @ForceInline
2058 public static void loadLoadFence() {
2059 UNSAFE.loadLoadFence();
2060 }
2061
2062 /**
2063 * Ensures that stores before the fence will not be reordered with
2064 * stores after the fence.
2065 */
2066 @ForceInline
2067 public static void storeStoreFence() {
2068 UNSAFE.storeStoreFence();
2069 }
2070 }