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