1 /*
   2  * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  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     @Override
1868     public final boolean equals(Object o) {
1869         if (this == o) return true;
1870         if (o == null || getClass() != o.getClass()) return false;
1871 
1872         VarHandle that = (VarHandle) o;
1873         return accessModeType(AccessMode.GET).equals(that.accessModeType(AccessMode.GET)) &&
1874                internalEquals(that);
1875     }
1876 
1877     abstract boolean internalEquals(VarHandle vh);
1878 
1879     @Override
1880     public final int hashCode() {
1881         return 31 * accessModeType(AccessMode.GET).hashCode() + internalHashCode();
1882     }
1883 
1884     abstract int internalHashCode();
1885 
1886     @Override
1887     public final String toString() {
1888         return String.format("VarHandle[varType=%s, coord=%s]",
1889                              varType().getName(),
1890                              coordinateTypes());
1891     }
1892 
1893     /**
1894      * Returns the variable type of variables referenced by this VarHandle.
1895      *
1896      * @return the variable type of variables referenced by this VarHandle
1897      */
1898     public final Class<?> varType() {
1899         MethodType typeSet = accessModeType(AccessMode.SET);
1900         return typeSet.parameterType(typeSet.parameterCount() - 1);
1901     }
1902 
1903     /**
1904      * Returns the coordinate types for this VarHandle.
1905      *
1906      * @return the coordinate types for this VarHandle. The returned
1907      * list is unmodifiable
1908      */
1909     public final List<Class<?>> coordinateTypes() {
1910         MethodType typeGet = accessModeType(AccessMode.GET);
1911         return typeGet.parameterList();
1912     }
1913 
1914     /**
1915      * Obtains the access mode type for this VarHandle and a given access mode.
1916      *
1917      * <p>The access mode type's parameter types will consist of a prefix that
1918      * is the coordinate types of this VarHandle followed by further
1919      * types as defined by the access mode method.
1920      * The access mode type's return type is defined by the return type of the
1921      * access mode method.
1922      *
1923      * @param accessMode the access mode, corresponding to the
1924      * signature-polymorphic method of the same name
1925      * @return the access mode type for the given access mode
1926      */
1927     public final MethodType accessModeType(AccessMode accessMode) {
1928         TypesAndInvokers tis = getTypesAndInvokers();
1929         MethodType mt = tis.methodType_table[accessMode.at.ordinal()];
1930         if (mt == null) {
1931             mt = tis.methodType_table[accessMode.at.ordinal()] =
1932                     accessModeTypeUncached(accessMode);
1933         }
1934         return mt;
1935     }
1936     abstract MethodType accessModeTypeUncached(AccessMode accessMode);
1937 
1938     /**
1939      * Returns {@code true} if the given access mode is supported, otherwise
1940      * {@code false}.
1941      *
1942      * <p>The return of a {@code false} value for a given access mode indicates
1943      * that an {@code UnsupportedOperationException} is thrown on invocation
1944      * of the corresponding access mode method.
1945      *
1946      * @param accessMode the access mode, corresponding to the
1947      * signature-polymorphic method of the same name
1948      * @return {@code true} if the given access mode is supported, otherwise
1949      * {@code false}.
1950      */
1951     public final boolean isAccessModeSupported(AccessMode accessMode) {
1952         return AccessMode.getMemberName(accessMode.ordinal(), vform) != null;
1953     }
1954 
1955     /**
1956      * Obtains a method handle bound to this VarHandle and the given access
1957      * mode.
1958      *
1959      * @apiNote This method, for a VarHandle {@code vh} and access mode
1960      * {@code {access-mode}}, returns a method handle that is equivalent to
1961      * method handle {@code bmh} in the following code (though it may be more
1962      * efficient):
1963      * <pre>{@code
1964      * MethodHandle mh = MethodHandles.varHandleExactInvoker(
1965      *                       vh.accessModeType(VarHandle.AccessMode.{access-mode}));
1966      *
1967      * MethodHandle bmh = mh.bindTo(vh);
1968      * }</pre>
1969      *
1970      * @param accessMode the access mode, corresponding to the
1971      * signature-polymorphic method of the same name
1972      * @return a method handle bound to this VarHandle and the given access mode
1973      */
1974     public final MethodHandle toMethodHandle(AccessMode accessMode) {
1975         MemberName mn = AccessMode.getMemberName(accessMode.ordinal(), vform);
1976         if (mn != null) {
1977             MethodHandle mh = getMethodHandle(accessMode.ordinal());
1978             return mh.bindTo(this);
1979         }
1980         else {
1981             // Ensure an UnsupportedOperationException is thrown
1982             return MethodHandles.varHandleInvoker(accessMode, accessModeType(accessMode)).
1983                     bindTo(this);
1984         }
1985     }
1986 
1987     /**
1988      * Return a nominal descriptor for this instance, if one can be
1989      * constructed, or an empty {@link Optional} if one cannot be.
1990      *
1991      * @return An {@link Optional} containing the resulting nominal descriptor,
1992      * or an empty {@link Optional} if one cannot be constructed.
1993      * @since 12
1994      */
1995     @Override
1996     public Optional<VarHandleDesc> describeConstable() {
1997         // partial function for field and array only
1998         return Optional.empty();
1999     }
2000 
2001     @Stable
2002     TypesAndInvokers typesAndInvokers;
2003 
2004     static class TypesAndInvokers {
2005         final @Stable
2006         MethodType[] methodType_table =
2007                 new MethodType[VarHandle.AccessType.values().length];
2008 
2009         final @Stable
2010         MethodHandle[] methodHandle_table =
2011                 new MethodHandle[AccessMode.values().length];
2012     }
2013 
2014     @ForceInline
2015     private final TypesAndInvokers getTypesAndInvokers() {
2016         TypesAndInvokers tis = typesAndInvokers;
2017         if (tis == null) {
2018             tis = typesAndInvokers = new TypesAndInvokers();
2019         }
2020         return tis;
2021     }
2022 
2023     @ForceInline
2024     final MethodHandle getMethodHandle(int mode) {
2025         TypesAndInvokers tis = getTypesAndInvokers();
2026         MethodHandle mh = tis.methodHandle_table[mode];
2027         if (mh == null) {
2028             mh = tis.methodHandle_table[mode] = getMethodHandleUncached(mode);
2029         }
2030         return mh;
2031     }
2032     private final MethodHandle getMethodHandleUncached(int mode) {
2033         MethodType mt = accessModeType(AccessMode.values()[mode]).
2034                 insertParameterTypes(0, VarHandle.class);
2035         MemberName mn = vform.getMemberName(mode);
2036         DirectMethodHandle dmh = DirectMethodHandle.make(mn);
2037         // Such a method handle must not be publically exposed directly
2038         // otherwise it can be cracked, it must be transformed or rebound
2039         // before exposure
2040         MethodHandle mh = dmh.copyWith(mt, dmh.form);
2041         assert mh.type().erase() == mn.getMethodType().erase();
2042         return mh;
2043     }
2044 
2045 
2046     /*non-public*/
2047     final void updateVarForm(VarForm newVForm) {
2048         if (vform == newVForm) return;
2049         UNSAFE.putReference(this, VFORM_OFFSET, newVForm);
2050         UNSAFE.fullFence();
2051     }
2052 
2053     static final BiFunction<String, List<Integer>, ArrayIndexOutOfBoundsException>
2054             AIOOBE_SUPPLIER = Preconditions.outOfBoundsExceptionFormatter(
2055             new Function<String, ArrayIndexOutOfBoundsException>() {
2056                 @Override
2057                 public ArrayIndexOutOfBoundsException apply(String s) {
2058                     return new ArrayIndexOutOfBoundsException(s);
2059                 }
2060             });
2061 
2062     private static final long VFORM_OFFSET;
2063 
2064     static {
2065         VFORM_OFFSET = UNSAFE.objectFieldOffset(VarHandle.class, "vform");
2066 
2067         // The VarHandleGuards must be initialized to ensure correct
2068         // compilation of the guard methods
2069         UNSAFE.ensureClassInitialized(VarHandleGuards.class);
2070     }
2071 
2072 
2073     // Fence methods
2074 
2075     /**
2076      * Ensures that loads and stores before the fence will not be reordered
2077      * with
2078      * loads and 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_seq_cst)}
2083      */
2084     @ForceInline
2085     public static void fullFence() {
2086         UNSAFE.fullFence();
2087     }
2088 
2089     /**
2090      * Ensures that loads before the fence will not be reordered with loads and
2091      * 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_acquire)}
2096      */
2097     @ForceInline
2098     public static void acquireFence() {
2099         UNSAFE.loadFence();
2100     }
2101 
2102     /**
2103      * Ensures that loads and stores before the fence will not be
2104      * reordered with stores after the fence.
2105      *
2106      * @apiNote Ignoring the many semantic differences from C and C++, this
2107      * method has memory ordering effects compatible with
2108      * {@code atomic_thread_fence(memory_order_release)}
2109      */
2110     @ForceInline
2111     public static void releaseFence() {
2112         UNSAFE.storeFence();
2113     }
2114 
2115     /**
2116      * Ensures that loads before the fence will not be reordered with
2117      * loads after the fence.
2118      */
2119     @ForceInline
2120     public static void loadLoadFence() {
2121         UNSAFE.loadLoadFence();
2122     }
2123 
2124     /**
2125      * Ensures that stores before the fence will not be reordered with
2126      * stores after the fence.
2127      */
2128     @ForceInline
2129     public static void storeStoreFence() {
2130         UNSAFE.storeStoreFence();
2131     }
2132 
2133     /**
2134      * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
2135      * {@link VarHandle} constant.
2136      *
2137      * @since 12
2138      */
2139     public static final class VarHandleDesc extends DynamicConstantDesc<VarHandle> {
2140 
2141         /**
2142          * Kinds of variable handle descs
2143          */
2144         private enum Kind {
2145             FIELD(ConstantDescs.BSM_VARHANDLE_FIELD),
2146             STATIC_FIELD(ConstantDescs.BSM_VARHANDLE_STATIC_FIELD),
2147             ARRAY(ConstantDescs.BSM_VARHANDLE_ARRAY);
2148 
2149             final DirectMethodHandleDesc bootstrapMethod;
2150 
2151             Kind(DirectMethodHandleDesc bootstrapMethod) {
2152                 this.bootstrapMethod = bootstrapMethod;
2153             }
2154 
2155             ConstantDesc[] toBSMArgs(ClassDesc declaringClass, ClassDesc varType) {
2156                 switch (this) {
2157                     case FIELD:
2158                     case STATIC_FIELD:
2159                         return new ConstantDesc[] {declaringClass, varType };
2160                     case ARRAY:
2161                         return new ConstantDesc[] {declaringClass };
2162                     default:
2163                         throw new InternalError("Cannot reach here");
2164                 }
2165             }
2166         }
2167 
2168         private final Kind kind;
2169         private final ClassDesc declaringClass;
2170         private final ClassDesc varType;
2171 
2172         /**
2173          * Construct a {@linkplain VarHandleDesc} given a kind, name, and declaring
2174          * class.
2175          *
2176          * @param kind the kind of of the var handle
2177          * @param name the unqualified name of the field, for field var handles; otherwise ignored
2178          * @param declaringClass a {@link ClassDesc} describing the declaring class,
2179          *                       for field var handles
2180          * @param varType a {@link ClassDesc} describing the type of the variable
2181          * @throws NullPointerException if any required argument is null
2182          * @jvms 4.2.2 Unqualified Names
2183          */
2184         private VarHandleDesc(Kind kind, String name, ClassDesc declaringClass, ClassDesc varType) {
2185             super(kind.bootstrapMethod, name,
2186                   ConstantDescs.CD_VarHandle,
2187                   kind.toBSMArgs(declaringClass, varType));
2188             this.kind = kind;
2189             this.declaringClass = declaringClass;
2190             this.varType = varType;
2191         }
2192 
2193         /**
2194          * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
2195          * for an instance field.
2196          *
2197          * @param name the unqualifed name of the field
2198          * @param declaringClass a {@link ClassDesc} describing the declaring class,
2199          *                       for field var handles
2200          * @param fieldType a {@link ClassDesc} describing the type of the field
2201          * @return the {@linkplain VarHandleDesc}
2202          * @throws NullPointerException if any of the arguments are null
2203          * @jvms 4.2.2 Unqualified Names
2204          */
2205         public static VarHandleDesc ofField(ClassDesc declaringClass, String name, ClassDesc fieldType) {
2206             Objects.requireNonNull(declaringClass);
2207             Objects.requireNonNull(name);
2208             Objects.requireNonNull(fieldType);
2209             return new VarHandleDesc(Kind.FIELD, name, declaringClass, fieldType);
2210         }
2211 
2212         /**
2213          * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
2214          * for a static field.
2215          *
2216          * @param name the unqualified name of the field
2217          * @param declaringClass a {@link ClassDesc} describing the declaring class,
2218          *                       for field var handles
2219          * @param fieldType a {@link ClassDesc} describing the type of the field
2220          * @return the {@linkplain VarHandleDesc}
2221          * @throws NullPointerException if any of the arguments are null
2222          * @jvms 4.2.2 Unqualified Names
2223          */
2224         public static VarHandleDesc ofStaticField(ClassDesc declaringClass, String name, ClassDesc fieldType) {
2225             Objects.requireNonNull(declaringClass);
2226             Objects.requireNonNull(name);
2227             Objects.requireNonNull(fieldType);
2228             return new VarHandleDesc(Kind.STATIC_FIELD, name, declaringClass, fieldType);
2229         }
2230 
2231         /**
2232          * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
2233          * for for an array type.
2234          *
2235          * @param arrayClass a {@link ClassDesc} describing the type of the array
2236          * @return the {@linkplain VarHandleDesc}
2237          * @throws NullPointerException if any of the arguments are null
2238          */
2239         public static VarHandleDesc ofArray(ClassDesc arrayClass) {
2240             Objects.requireNonNull(arrayClass);
2241             if (!arrayClass.isArray())
2242                 throw new IllegalArgumentException("Array class argument not an array: " + arrayClass);
2243             return new VarHandleDesc(Kind.ARRAY, ConstantDescs.DEFAULT_NAME, arrayClass, arrayClass.componentType());
2244         }
2245 
2246         /**
2247          * Returns a {@link ClassDesc} describing the type of the variable described
2248          * by this descriptor.
2249          *
2250          * @return the variable type
2251          */
2252         public ClassDesc varType() {
2253             return varType;
2254         }
2255 
2256         @Override
2257         public VarHandle resolveConstantDesc(MethodHandles.Lookup lookup)
2258                 throws ReflectiveOperationException {
2259             switch (kind) {
2260                 case FIELD:
2261                     return lookup.findVarHandle((Class<?>) declaringClass.resolveConstantDesc(lookup),
2262                                                 constantName(),
2263                                                 (Class<?>) varType.resolveConstantDesc(lookup));
2264                 case STATIC_FIELD:
2265                     return lookup.findStaticVarHandle((Class<?>) declaringClass.resolveConstantDesc(lookup),
2266                                                       constantName(),
2267                                                       (Class<?>) varType.resolveConstantDesc(lookup));
2268                 case ARRAY:
2269                     return MethodHandles.arrayElementVarHandle((Class<?>) declaringClass.resolveConstantDesc(lookup));
2270                 default:
2271                     throw new InternalError("Cannot reach here");
2272             }
2273         }
2274 
2275         @Override
2276         public String toString() {
2277             switch (kind) {
2278                 case FIELD:
2279                 case STATIC_FIELD:
2280                     return String.format("VarHandleDesc[%s%s.%s:%s]",
2281                                          (kind == Kind.STATIC_FIELD) ? "static " : "",
2282                                          declaringClass.displayName(), constantName(), varType.displayName());
2283                 case ARRAY:
2284                     return String.format("VarHandleDesc[%s[]]", declaringClass.displayName());
2285                 default:
2286                     throw new InternalError("Cannot reach here");
2287             }
2288         }
2289     }
2290 
2291 }