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