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