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