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             // the field type (value) is mapped to the return type of MethodType
1555             // the receiver type is mapped to a parameter type of MethodType
1556             // So use the value type as receiver may be a box type.
1557             if (receiver != null)
1558                 receiver = receiver.asPrimaryType();
1559             switch (this) {
1560                 case GET:
1561                     ps = allocateParameters(0, receiver, intermediate);
1562                     fillParameters(ps, receiver, intermediate);
1563                     return MethodType.methodType(value, ps);
1564                 case SET:
1565                     ps = allocateParameters(1, receiver, intermediate);
1566                     i = fillParameters(ps, receiver, intermediate);
1567                     ps[i] = value;
1568                     return MethodType.methodType(void.class, ps);
1569                 case COMPARE_AND_SET:
1570                     ps = allocateParameters(2, receiver, intermediate);
1571                     i = fillParameters(ps, receiver, intermediate);
1572                     ps[i++] = value;
1573                     ps[i] = value;
1574                     return MethodType.methodType(boolean.class, ps);
1575                 case COMPARE_AND_EXCHANGE:
1576                     ps = allocateParameters(2, receiver, intermediate);
1577                     i = fillParameters(ps, receiver, intermediate);
1578                     ps[i++] = value;
1579                     ps[i] = value;
1580                     return MethodType.methodType(value, ps);
1581                 case GET_AND_UPDATE:
1582                     ps = allocateParameters(1, receiver, intermediate);
1583                     i = fillParameters(ps, receiver, intermediate);
1584                     ps[i] = value;
1585                     return MethodType.methodType(value, ps);
1586                 default:
1587                     throw new InternalError("Unknown AccessType");
1588             }
1589         }
1590 
1591         private static Class<?>[] allocateParameters(int values,
1592                                                      Class<?> receiver, Class<?>... intermediate) {
1593             int size = ((receiver != null) ? 1 : 0) + intermediate.length + values;
1594             return new Class<?>[size];
1595         }
1596 
1597         private static int fillParameters(Class<?>[] ps,
1598                                           Class<?> receiver, Class<?>... intermediate) {
1599             int i = 0;
1600             if (receiver != null)
1601                 ps[i++] = receiver;
1602             for (int j = 0; j < intermediate.length; j++)
1603                 ps[i++] = intermediate[j];
1604             return i;
1605         }
1606     }
1607 
1608     /**
1609      * The set of access modes that specify how a variable, referenced by a
1610      * VarHandle, is accessed.
1611      */
1612     public enum AccessMode {
1613         /**
1614          * The access mode whose access is specified by the corresponding
1615          * method
1616          * {@link VarHandle#get VarHandle.get}
1617          */
1618         GET("get", AccessType.GET),
1619         /**
1620          * The access mode whose access is specified by the corresponding
1621          * method
1622          * {@link VarHandle#set VarHandle.set}
1623          */
1624         SET("set", AccessType.SET),
1625         /**
1626          * The access mode whose access is specified by the corresponding
1627          * method
1628          * {@link VarHandle#getVolatile VarHandle.getVolatile}
1629          */
1630         GET_VOLATILE("getVolatile", AccessType.GET),
1631         /**
1632          * The access mode whose access is specified by the corresponding
1633          * method
1634          * {@link VarHandle#setVolatile VarHandle.setVolatile}
1635          */
1636         SET_VOLATILE("setVolatile", AccessType.SET),
1637         /**
1638          * The access mode whose access is specified by the corresponding
1639          * method
1640          * {@link VarHandle#getAcquire VarHandle.getAcquire}
1641          */
1642         GET_ACQUIRE("getAcquire", AccessType.GET),
1643         /**
1644          * The access mode whose access is specified by the corresponding
1645          * method
1646          * {@link VarHandle#setRelease VarHandle.setRelease}
1647          */
1648         SET_RELEASE("setRelease", AccessType.SET),
1649         /**
1650          * The access mode whose access is specified by the corresponding
1651          * method
1652          * {@link VarHandle#getOpaque VarHandle.getOpaque}
1653          */
1654         GET_OPAQUE("getOpaque", AccessType.GET),
1655         /**
1656          * The access mode whose access is specified by the corresponding
1657          * method
1658          * {@link VarHandle#setOpaque VarHandle.setOpaque}
1659          */
1660         SET_OPAQUE("setOpaque", AccessType.SET),
1661         /**
1662          * The access mode whose access is specified by the corresponding
1663          * method
1664          * {@link VarHandle#compareAndSet VarHandle.compareAndSet}
1665          */
1666         COMPARE_AND_SET("compareAndSet", AccessType.COMPARE_AND_SET),
1667         /**
1668          * The access mode whose access is specified by the corresponding
1669          * method
1670          * {@link VarHandle#compareAndExchange VarHandle.compareAndExchange}
1671          */
1672         COMPARE_AND_EXCHANGE("compareAndExchange", AccessType.COMPARE_AND_EXCHANGE),
1673         /**
1674          * The access mode whose access is specified by the corresponding
1675          * method
1676          * {@link VarHandle#compareAndExchangeAcquire VarHandle.compareAndExchangeAcquire}
1677          */
1678         COMPARE_AND_EXCHANGE_ACQUIRE("compareAndExchangeAcquire", AccessType.COMPARE_AND_EXCHANGE),
1679         /**
1680          * The access mode whose access is specified by the corresponding
1681          * method
1682          * {@link VarHandle#compareAndExchangeRelease VarHandle.compareAndExchangeRelease}
1683          */
1684         COMPARE_AND_EXCHANGE_RELEASE("compareAndExchangeRelease", AccessType.COMPARE_AND_EXCHANGE),
1685         /**
1686          * The access mode whose access is specified by the corresponding
1687          * method
1688          * {@link VarHandle#weakCompareAndSetPlain VarHandle.weakCompareAndSetPlain}
1689          */
1690         WEAK_COMPARE_AND_SET_PLAIN("weakCompareAndSetPlain", AccessType.COMPARE_AND_SET),
1691         /**
1692          * The access mode whose access is specified by the corresponding
1693          * method
1694          * {@link VarHandle#weakCompareAndSet VarHandle.weakCompareAndSet}
1695          */
1696         WEAK_COMPARE_AND_SET("weakCompareAndSet", AccessType.COMPARE_AND_SET),
1697         /**
1698          * The access mode whose access is specified by the corresponding
1699          * method
1700          * {@link VarHandle#weakCompareAndSetAcquire VarHandle.weakCompareAndSetAcquire}
1701          */
1702         WEAK_COMPARE_AND_SET_ACQUIRE("weakCompareAndSetAcquire", AccessType.COMPARE_AND_SET),
1703         /**
1704          * The access mode whose access is specified by the corresponding
1705          * method
1706          * {@link VarHandle#weakCompareAndSetRelease VarHandle.weakCompareAndSetRelease}
1707          */
1708         WEAK_COMPARE_AND_SET_RELEASE("weakCompareAndSetRelease", AccessType.COMPARE_AND_SET),
1709         /**
1710          * The access mode whose access is specified by the corresponding
1711          * method
1712          * {@link VarHandle#getAndSet VarHandle.getAndSet}
1713          */
1714         GET_AND_SET("getAndSet", AccessType.GET_AND_UPDATE),
1715         /**
1716          * The access mode whose access is specified by the corresponding
1717          * method
1718          * {@link VarHandle#getAndSetAcquire VarHandle.getAndSetAcquire}
1719          */
1720         GET_AND_SET_ACQUIRE("getAndSetAcquire", AccessType.GET_AND_UPDATE),
1721         /**
1722          * The access mode whose access is specified by the corresponding
1723          * method
1724          * {@link VarHandle#getAndSetRelease VarHandle.getAndSetRelease}
1725          */
1726         GET_AND_SET_RELEASE("getAndSetRelease", AccessType.GET_AND_UPDATE),
1727         /**
1728          * The access mode whose access is specified by the corresponding
1729          * method
1730          * {@link VarHandle#getAndAdd VarHandle.getAndAdd}
1731          */
1732         GET_AND_ADD("getAndAdd", AccessType.GET_AND_UPDATE),
1733         /**
1734          * The access mode whose access is specified by the corresponding
1735          * method
1736          * {@link VarHandle#getAndAddAcquire VarHandle.getAndAddAcquire}
1737          */
1738         GET_AND_ADD_ACQUIRE("getAndAddAcquire", AccessType.GET_AND_UPDATE),
1739         /**
1740          * The access mode whose access is specified by the corresponding
1741          * method
1742          * {@link VarHandle#getAndAddRelease VarHandle.getAndAddRelease}
1743          */
1744         GET_AND_ADD_RELEASE("getAndAddRelease", AccessType.GET_AND_UPDATE),
1745         /**
1746          * The access mode whose access is specified by the corresponding
1747          * method
1748          * {@link VarHandle#getAndBitwiseOr VarHandle.getAndBitwiseOr}
1749          */
1750         GET_AND_BITWISE_OR("getAndBitwiseOr", AccessType.GET_AND_UPDATE),
1751         /**
1752          * The access mode whose access is specified by the corresponding
1753          * method
1754          * {@link VarHandle#getAndBitwiseOrRelease VarHandle.getAndBitwiseOrRelease}
1755          */
1756         GET_AND_BITWISE_OR_RELEASE("getAndBitwiseOrRelease", AccessType.GET_AND_UPDATE),
1757         /**
1758          * The access mode whose access is specified by the corresponding
1759          * method
1760          * {@link VarHandle#getAndBitwiseOrAcquire VarHandle.getAndBitwiseOrAcquire}
1761          */
1762         GET_AND_BITWISE_OR_ACQUIRE("getAndBitwiseOrAcquire", AccessType.GET_AND_UPDATE),
1763         /**
1764          * The access mode whose access is specified by the corresponding
1765          * method
1766          * {@link VarHandle#getAndBitwiseAnd VarHandle.getAndBitwiseAnd}
1767          */
1768         GET_AND_BITWISE_AND("getAndBitwiseAnd", AccessType.GET_AND_UPDATE),
1769         /**
1770          * The access mode whose access is specified by the corresponding
1771          * method
1772          * {@link VarHandle#getAndBitwiseAndRelease VarHandle.getAndBitwiseAndRelease}
1773          */
1774         GET_AND_BITWISE_AND_RELEASE("getAndBitwiseAndRelease", AccessType.GET_AND_UPDATE),
1775         /**
1776          * The access mode whose access is specified by the corresponding
1777          * method
1778          * {@link VarHandle#getAndBitwiseAndAcquire VarHandle.getAndBitwiseAndAcquire}
1779          */
1780         GET_AND_BITWISE_AND_ACQUIRE("getAndBitwiseAndAcquire", AccessType.GET_AND_UPDATE),
1781         /**
1782          * The access mode whose access is specified by the corresponding
1783          * method
1784          * {@link VarHandle#getAndBitwiseXor VarHandle.getAndBitwiseXor}
1785          */
1786         GET_AND_BITWISE_XOR("getAndBitwiseXor", AccessType.GET_AND_UPDATE),
1787         /**
1788          * The access mode whose access is specified by the corresponding
1789          * method
1790          * {@link VarHandle#getAndBitwiseXorRelease VarHandle.getAndBitwiseXorRelease}
1791          */
1792         GET_AND_BITWISE_XOR_RELEASE("getAndBitwiseXorRelease", AccessType.GET_AND_UPDATE),
1793         /**
1794          * The access mode whose access is specified by the corresponding
1795          * method
1796          * {@link VarHandle#getAndBitwiseXorAcquire VarHandle.getAndBitwiseXorAcquire}
1797          */
1798         GET_AND_BITWISE_XOR_ACQUIRE("getAndBitwiseXorAcquire", AccessType.GET_AND_UPDATE),
1799         ;
1800 
1801         static final Map<String, AccessMode> methodNameToAccessMode;
1802         static {
1803             AccessMode[] values = AccessMode.values();
1804             // Initial capacity of # values divided by the load factor is sufficient
1805             // to avoid resizes for the smallest table size (64)
1806             int initialCapacity = (int)(values.length / 0.75f) + 1;
1807             methodNameToAccessMode = new HashMap<>(initialCapacity);
1808             for (AccessMode am : values) {
1809                 methodNameToAccessMode.put(am.methodName, am);
1810             }
1811         }
1812 
1813         final String methodName;
1814         final AccessType at;
1815 
1816         AccessMode(final String methodName, AccessType at) {
1817             this.methodName = methodName;
1818             this.at = at;
1819         }
1820 
1821         /**
1822          * Returns the {@code VarHandle} signature-polymorphic method name
1823          * associated with this {@code AccessMode} value.
1824          *
1825          * @return the signature-polymorphic method name
1826          * @see #valueFromMethodName
1827          */
1828         public String methodName() {
1829             return methodName;
1830         }
1831 
1832         /**
1833          * Returns the {@code AccessMode} value associated with the specified
1834          * {@code VarHandle} signature-polymorphic method name.
1835          *
1836          * @param methodName the signature-polymorphic method name
1837          * @return the {@code AccessMode} value
1838          * @throws IllegalArgumentException if there is no {@code AccessMode}
1839          *         value associated with method name (indicating the method
1840          *         name does not correspond to a {@code VarHandle}
1841          *         signature-polymorphic method name).
1842          * @see #methodName()
1843          */
1844         public static AccessMode valueFromMethodName(String methodName) {
1845             AccessMode am = methodNameToAccessMode.get(methodName);
1846             if (am != null) return am;
1847             throw new IllegalArgumentException("No AccessMode value for method name " + methodName);
1848         }
1849 
1850         @ForceInline
1851         static MemberName getMemberName(int ordinal, VarForm vform) {
1852             return vform.memberName_table[ordinal];
1853         }
1854     }
1855 
1856     static final class AccessDescriptor {
1857         final MethodType symbolicMethodTypeErased;
1858         final MethodType symbolicMethodTypeInvoker;
1859         final Class<?> returnType;
1860         final int type;
1861         final int mode;
1862 
1863         public AccessDescriptor(MethodType symbolicMethodType, int type, int mode) {
1864             this.symbolicMethodTypeErased = symbolicMethodType.erase();
1865             this.symbolicMethodTypeInvoker = symbolicMethodType.insertParameterTypes(0, VarHandle.class);
1866             this.returnType = symbolicMethodType.returnType();
1867             this.type = type;
1868             this.mode = mode;
1869         }
1870     }
1871 
1872     /**
1873      * Returns a compact textual description of this {@linkplain VarHandle},
1874      * including the type of variable described, and a description of its coordinates.
1875      *
1876      * @return A compact textual description of this {@linkplain VarHandle}
1877      */
1878     @Override
1879     public final String toString() {
1880         return String.format("VarHandle[varType=%s, coord=%s]",
1881                              varType().getName(),
1882                              coordinateTypes());
1883     }
1884 
1885     /**
1886      * Returns the variable type of variables referenced by this VarHandle.
1887      *
1888      * @return the variable type of variables referenced by this VarHandle
1889      */
1890     public final Class<?> varType() {
1891         MethodType typeSet = accessModeType(AccessMode.SET);
1892         return typeSet.parameterType(typeSet.parameterCount() - 1);
1893     }
1894 
1895     /**
1896      * Returns the coordinate types for this VarHandle.
1897      *
1898      * @return the coordinate types for this VarHandle. The returned
1899      * list is unmodifiable
1900      */
1901     public final List<Class<?>> coordinateTypes() {
1902         MethodType typeGet = accessModeType(AccessMode.GET);
1903         return typeGet.parameterList();
1904     }
1905 
1906     /**
1907      * Obtains the access mode type for this VarHandle and a given access mode.
1908      *
1909      * <p>The access mode type's parameter types will consist of a prefix that
1910      * is the coordinate types of this VarHandle followed by further
1911      * types as defined by the access mode method.
1912      * The access mode type's return type is defined by the return type of the
1913      * access mode method.
1914      *
1915      * @param accessMode the access mode, corresponding to the
1916      * signature-polymorphic method of the same name
1917      * @return the access mode type for the given access mode
1918      */
1919     public final MethodType accessModeType(AccessMode accessMode) {
1920         TypesAndInvokers tis = getTypesAndInvokers();
1921         MethodType mt = tis.methodType_table[accessMode.at.ordinal()];
1922         if (mt == null) {
1923             mt = tis.methodType_table[accessMode.at.ordinal()] =
1924                     accessModeTypeUncached(accessMode);
1925         }
1926         return mt;
1927     }
1928     abstract MethodType accessModeTypeUncached(AccessMode accessMode);
1929 
1930     /**
1931      * Returns {@code true} if the given access mode is supported, otherwise
1932      * {@code false}.
1933      *
1934      * <p>The return of a {@code false} value for a given access mode indicates
1935      * that an {@code UnsupportedOperationException} is thrown on invocation
1936      * of the corresponding access mode method.
1937      *
1938      * @param accessMode the access mode, corresponding to the
1939      * signature-polymorphic method of the same name
1940      * @return {@code true} if the given access mode is supported, otherwise
1941      * {@code false}.
1942      */
1943     public final boolean isAccessModeSupported(AccessMode accessMode) {
1944         return AccessMode.getMemberName(accessMode.ordinal(), vform) != null;
1945     }
1946 
1947     /**
1948      * Obtains a method handle bound to this VarHandle and the given access
1949      * mode.
1950      *
1951      * @apiNote This method, for a VarHandle {@code vh} and access mode
1952      * {@code {access-mode}}, returns a method handle that is equivalent to
1953      * method handle {@code bmh} in the following code (though it may be more
1954      * efficient):
1955      * <pre>{@code
1956      * MethodHandle mh = MethodHandles.varHandleExactInvoker(
1957      *                       vh.accessModeType(VarHandle.AccessMode.{access-mode}));
1958      *
1959      * MethodHandle bmh = mh.bindTo(vh);
1960      * }</pre>
1961      *
1962      * @param accessMode the access mode, corresponding to the
1963      * signature-polymorphic method of the same name
1964      * @return a method handle bound to this VarHandle and the given access mode
1965      */
1966     public final MethodHandle toMethodHandle(AccessMode accessMode) {
1967         MemberName mn = AccessMode.getMemberName(accessMode.ordinal(), vform);
1968         if (mn != null) {
1969             MethodHandle mh = getMethodHandle(accessMode.ordinal());
1970             return mh.bindTo(this);
1971         }
1972         else {
1973             // Ensure an UnsupportedOperationException is thrown
1974             return MethodHandles.varHandleInvoker(accessMode, accessModeType(accessMode)).
1975                     bindTo(this);
1976         }
1977     }
1978 
1979     /**
1980      * Return a nominal descriptor for this instance, if one can be
1981      * constructed, or an empty {@link Optional} if one cannot be.
1982      *
1983      * @return An {@link Optional} containing the resulting nominal descriptor,
1984      * or an empty {@link Optional} if one cannot be constructed.
1985      * @since 12
1986      */
1987     @Override
1988     public Optional<VarHandleDesc> describeConstable() {
1989         // partial function for field and array only
1990         return Optional.empty();
1991     }
1992 
1993     @Stable
1994     TypesAndInvokers typesAndInvokers;
1995 
1996     static class TypesAndInvokers {
1997         final @Stable
1998         MethodType[] methodType_table =
1999                 new MethodType[VarHandle.AccessType.values().length];
2000 
2001         final @Stable
2002         MethodHandle[] methodHandle_table =
2003                 new MethodHandle[AccessMode.values().length];
2004     }
2005 
2006     @ForceInline
2007     private final TypesAndInvokers getTypesAndInvokers() {
2008         TypesAndInvokers tis = typesAndInvokers;
2009         if (tis == null) {
2010             tis = typesAndInvokers = new TypesAndInvokers();
2011         }
2012         return tis;
2013     }
2014 
2015     @ForceInline
2016     final MethodHandle getMethodHandle(int mode) {
2017         TypesAndInvokers tis = getTypesAndInvokers();
2018         MethodHandle mh = tis.methodHandle_table[mode];
2019         if (mh == null) {
2020             mh = tis.methodHandle_table[mode] = getMethodHandleUncached(mode);
2021         }
2022         return mh;
2023     }
2024     private final MethodHandle getMethodHandleUncached(int mode) {
2025         MethodType mt = accessModeType(AccessMode.values()[mode]).
2026                 insertParameterTypes(0, VarHandle.class);
2027         MemberName mn = vform.getMemberName(mode);
2028         DirectMethodHandle dmh = DirectMethodHandle.make(mn);
2029         // Such a method handle must not be publically exposed directly
2030         // otherwise it can be cracked, it must be transformed or rebound
2031         // before exposure
2032         MethodHandle mh = dmh.copyWith(mt, dmh.form);
2033         assert mh.type().erase() == mn.getMethodType().erase();
2034         return mh;
2035     }
2036 
2037 
2038     /*non-public*/
2039     final void updateVarForm(VarForm newVForm) {
2040         if (vform == newVForm) return;
2041         UNSAFE.putReference(this, VFORM_OFFSET, newVForm);
2042         UNSAFE.fullFence();
2043     }
2044 
2045     static final BiFunction<String, List<Integer>, ArrayIndexOutOfBoundsException>
2046             AIOOBE_SUPPLIER = Preconditions.outOfBoundsExceptionFormatter(
2047             new Function<String, ArrayIndexOutOfBoundsException>() {
2048                 @Override
2049                 public ArrayIndexOutOfBoundsException apply(String s) {
2050                     return new ArrayIndexOutOfBoundsException(s);
2051                 }
2052             });
2053 
2054     private static final long VFORM_OFFSET;
2055 
2056     static {
2057         VFORM_OFFSET = UNSAFE.objectFieldOffset(VarHandle.class, "vform");
2058 
2059         // The VarHandleGuards must be initialized to ensure correct
2060         // compilation of the guard methods
2061         UNSAFE.ensureClassInitialized(VarHandleGuards.class);
2062     }
2063 
2064 
2065     // Fence methods
2066 
2067     /**
2068      * Ensures that loads and stores before the fence will not be reordered
2069      * with
2070      * loads and stores after the fence.
2071      *
2072      * @apiNote Ignoring the many semantic differences from C and C++, this
2073      * method has memory ordering effects compatible with
2074      * {@code atomic_thread_fence(memory_order_seq_cst)}
2075      */
2076     @ForceInline
2077     public static void fullFence() {
2078         UNSAFE.fullFence();
2079     }
2080 
2081     /**
2082      * Ensures that loads before the fence will not be reordered with loads and
2083      * stores after the fence.
2084      *
2085      * @apiNote Ignoring the many semantic differences from C and C++, this
2086      * method has memory ordering effects compatible with
2087      * {@code atomic_thread_fence(memory_order_acquire)}
2088      */
2089     @ForceInline
2090     public static void acquireFence() {
2091         UNSAFE.loadFence();
2092     }
2093 
2094     /**
2095      * Ensures that loads and stores before the fence will not be
2096      * reordered with stores after the fence.
2097      *
2098      * @apiNote Ignoring the many semantic differences from C and C++, this
2099      * method has memory ordering effects compatible with
2100      * {@code atomic_thread_fence(memory_order_release)}
2101      */
2102     @ForceInline
2103     public static void releaseFence() {
2104         UNSAFE.storeFence();
2105     }
2106 
2107     /**
2108      * Ensures that loads before the fence will not be reordered with
2109      * loads after the fence.
2110      */
2111     @ForceInline
2112     public static void loadLoadFence() {
2113         UNSAFE.loadLoadFence();
2114     }
2115 
2116     /**
2117      * Ensures that stores before the fence will not be reordered with
2118      * stores after the fence.
2119      */
2120     @ForceInline
2121     public static void storeStoreFence() {
2122         UNSAFE.storeStoreFence();
2123     }
2124 
2125     /**
2126      * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
2127      * {@link VarHandle} constant.
2128      *
2129      * @since 12
2130      */
2131     public static final class VarHandleDesc extends DynamicConstantDesc<VarHandle> {
2132 
2133         /**
2134          * Kinds of variable handle descs
2135          */
2136         private enum Kind {
2137             FIELD(ConstantDescs.BSM_VARHANDLE_FIELD),
2138             STATIC_FIELD(ConstantDescs.BSM_VARHANDLE_STATIC_FIELD),
2139             ARRAY(ConstantDescs.BSM_VARHANDLE_ARRAY);
2140 
2141             final DirectMethodHandleDesc bootstrapMethod;
2142 
2143             Kind(DirectMethodHandleDesc bootstrapMethod) {
2144                 this.bootstrapMethod = bootstrapMethod;
2145             }
2146 
2147             ConstantDesc[] toBSMArgs(ClassDesc declaringClass, ClassDesc varType) {
2148                 switch (this) {
2149                     case FIELD:
2150                     case STATIC_FIELD:
2151                         return new ConstantDesc[] {declaringClass, varType };
2152                     case ARRAY:
2153                         return new ConstantDesc[] {declaringClass };
2154                     default:
2155                         throw new InternalError("Cannot reach here");
2156                 }
2157             }
2158         }
2159 
2160         private final Kind kind;
2161         private final ClassDesc declaringClass;
2162         private final ClassDesc varType;
2163 
2164         /**
2165          * Construct a {@linkplain VarHandleDesc} given a kind, name, and declaring
2166          * class.
2167          *
2168          * @param kind the kind of the var handle
2169          * @param name the unqualified name of the field, for field var handles; otherwise ignored
2170          * @param declaringClass a {@link ClassDesc} describing the declaring class,
2171          *                       for field var handles
2172          * @param varType a {@link ClassDesc} describing the type of the variable
2173          * @throws NullPointerException if any required argument is null
2174          * @jvms 4.2.2 Unqualified Names
2175          */
2176         private VarHandleDesc(Kind kind, String name, ClassDesc declaringClass, ClassDesc varType) {
2177             super(kind.bootstrapMethod, name,
2178                   ConstantDescs.CD_VarHandle,
2179                   kind.toBSMArgs(declaringClass, varType));
2180             this.kind = kind;
2181             this.declaringClass = declaringClass;
2182             this.varType = varType;
2183         }
2184 
2185         /**
2186          * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
2187          * for an instance field.
2188          *
2189          * @param name the unqualifed name of the field
2190          * @param declaringClass a {@link ClassDesc} describing the declaring class,
2191          *                       for field var handles
2192          * @param fieldType a {@link ClassDesc} describing the type of the field
2193          * @return the {@linkplain VarHandleDesc}
2194          * @throws NullPointerException if any of the arguments are null
2195          * @jvms 4.2.2 Unqualified Names
2196          */
2197         public static VarHandleDesc ofField(ClassDesc declaringClass, String name, ClassDesc fieldType) {
2198             Objects.requireNonNull(declaringClass);
2199             Objects.requireNonNull(name);
2200             Objects.requireNonNull(fieldType);
2201             return new VarHandleDesc(Kind.FIELD, name, declaringClass, fieldType);
2202         }
2203 
2204         /**
2205          * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
2206          * for a static field.
2207          *
2208          * @param name the unqualified name of the field
2209          * @param declaringClass a {@link ClassDesc} describing the declaring class,
2210          *                       for field var handles
2211          * @param fieldType a {@link ClassDesc} describing the type of the field
2212          * @return the {@linkplain VarHandleDesc}
2213          * @throws NullPointerException if any of the arguments are null
2214          * @jvms 4.2.2 Unqualified Names
2215          */
2216         public static VarHandleDesc ofStaticField(ClassDesc declaringClass, String name, ClassDesc fieldType) {
2217             Objects.requireNonNull(declaringClass);
2218             Objects.requireNonNull(name);
2219             Objects.requireNonNull(fieldType);
2220             return new VarHandleDesc(Kind.STATIC_FIELD, name, declaringClass, fieldType);
2221         }
2222 
2223         /**
2224          * Returns a {@linkplain VarHandleDesc} corresponding to a {@link VarHandle}
2225          * for an array type.
2226          *
2227          * @param arrayClass a {@link ClassDesc} describing the type of the array
2228          * @return the {@linkplain VarHandleDesc}
2229          * @throws NullPointerException if any of the arguments are null
2230          */
2231         public static VarHandleDesc ofArray(ClassDesc arrayClass) {
2232             Objects.requireNonNull(arrayClass);
2233             if (!arrayClass.isArray())
2234                 throw new IllegalArgumentException("Array class argument not an array: " + arrayClass);
2235             return new VarHandleDesc(Kind.ARRAY, ConstantDescs.DEFAULT_NAME, arrayClass, arrayClass.componentType());
2236         }
2237 
2238         /**
2239          * Returns a {@link ClassDesc} describing the type of the variable described
2240          * by this descriptor.
2241          *
2242          * @return the variable type
2243          */
2244         public ClassDesc varType() {
2245             return varType;
2246         }
2247 
2248         @Override
2249         public VarHandle resolveConstantDesc(MethodHandles.Lookup lookup)
2250                 throws ReflectiveOperationException {
2251             switch (kind) {
2252                 case FIELD:
2253                     return lookup.findVarHandle((Class<?>) declaringClass.resolveConstantDesc(lookup),
2254                                                 constantName(),
2255                                                 (Class<?>) varType.resolveConstantDesc(lookup));
2256                 case STATIC_FIELD:
2257                     return lookup.findStaticVarHandle((Class<?>) declaringClass.resolveConstantDesc(lookup),
2258                                                       constantName(),
2259                                                       (Class<?>) varType.resolveConstantDesc(lookup));
2260                 case ARRAY:
2261                     return MethodHandles.arrayElementVarHandle((Class<?>) declaringClass.resolveConstantDesc(lookup));
2262                 default:
2263                     throw new InternalError("Cannot reach here");
2264             }
2265         }
2266 
2267         /**
2268          * Returns a compact textual description of this constant description.
2269          * For a field {@linkplain VarHandle}, includes the owner, name, and type
2270          * of the field, and whether it is static; for an array {@linkplain VarHandle},
2271          * the name of the component type.
2272          *
2273          * @return A compact textual description of this descriptor
2274          */
2275         @Override
2276         public String toString() {
2277             switch (kind) {
2278                 case FIELD:
2279                 case STATIC_FIELD:
2280                     return String.format("VarHandleDesc[%s%s.%s:%s]",
2281                                          (kind == Kind.STATIC_FIELD) ? "static " : "",
2282                                          declaringClass.displayName(), constantName(), varType.displayName());
2283                 case ARRAY:
2284                     return String.format("VarHandleDesc[%s[]]", declaringClass.displayName());
2285                 default:
2286                     throw new InternalError("Cannot reach here");
2287             }
2288         }
2289     }
2290 
2291 }