1 /*
   2  * Copyright (c) 2014, 2015, 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 jdk.internal.HotSpotIntrinsicCandidate;
  29 import jdk.internal.vm.annotation.ForceInline;
  30 import jdk.internal.vm.annotation.Stable;
  31 
  32 import java.lang.reflect.Method;
  33 import java.util.HashMap;
  34 import java.util.List;
  35 import java.util.Map;
  36 import java.util.Objects;
  37 import java.util.function.BiFunction;
  38 import java.util.function.Function;
  39 
  40 import static java.lang.invoke.MethodHandleStatics.UNSAFE;
  41 import static java.lang.invoke.MethodHandleStatics.newInternalError;
  42 
  43 /**
  44  * A VarHandle is a dynamically typed reference to a variable, or to a
  45  * parametrically-defined family of variables, including static fields,
  46  * non-static fields, array elements, or components of an off-heap data
  47  * structure.  Access to such variables is supported under various
  48  * <em>access modes</em>, including plain read/write access, volatile
  49  * read/write access, and compare-and-swap.
  50  *
  51  * <p>VarHandles are immutable and have no visible state.  VarHandles cannot be
  52  * subclassed by the user.
  53  *
  54  * <p>A VarHandle has:
  55  * <ul>
  56  * <li>a {@link #varType variable type}, referred to as {@code T}, which is the
  57  * type of variable(s) referenced by this VarHandle;
  58  * <li>a list of {@link #coordinateTypes coordinate types}, referred to as
  59  * {@code CT}, where the types (primitive and reference) are represented by
  60  * {@link Class} objects).  A list of arguments corresponding to instances of
  61  * the coordinate types uniquely locates a variable referenced by this
  62  * VarHandle; and
  63  * <li>a <em>shape</em>, that combines the variable type and coordinate types,
  64  * and is declared with the notation {@code (CT : T)}.  An empty list of
  65  * coordinate types is declared as {@code (empty)}.
  66  * </ul>
  67  *
  68  * <p>Factory methods that produce or {@link java.lang.invoke.MethodHandles.Lookup
  69  * lookup} VarHandle instances document the supported variable type, coordinate
  70  * types, and shape.
  71  *
  72  * For example, a VarHandle referencing a non-static field will declare a shape
  73  * of {@code (R : T)}, where {@code R} is the receiver type and
  74  * {@code T} is the field type, and where the VarHandle and an instance of the
  75  * receiver type can be utilized to access the field variable.
  76  * A VarHandle referencing array elements will declare a shape of
  77  * {@code (T[], int : T)}, where {@code T[]} is the array type and {@code T}
  78  * its component type, and where the VarHandle, an instance of the array type,
  79  * and an {@code int} index can be utilized to access an array element variable.
  80  *
  81  * <p>Each access mode is associated with a
  82  * <a href="MethodHandle.html#sigpoly">signature polymorphic</a> method of the
  83  * same name, where the VarHandle shape and access mode uniquely determine the
  84  * canonical {@link #accessModeType(AccessMode) access mode type},
  85  * which in turn determines the matching constraints on a valid symbolic
  86  * type descriptor at the call site of an access mode's method
  87  * <a href="VarHandle.html#invoke">invocation</a>.
  88  *
  89  * As such, VarHandles are dynamically and strongly typed.  Their arity,
  90  * argument types, and return type of an access mode method invocation are not
  91  * statically checked.  If they, and associated values, do not match the arity
  92  * and types of the access mode's type, an exception will be thrown.
  93  *
  94  * The parameter types of an access mode method type will consist of those that
  95  * are the VarHandles's coordinate types (in order), followed by access mode
  96  * parameter types specific to the access mode.
  97  *
  98  * <p>An access mode's method documents the form of its method signature, which
  99  * is derived from the access mode parameter types.  The form is declared with
 100  * the notation {@code (CT, P1 p1, P2 p2, ..., PN pn)R}, where {@code CT} is the
 101  * coordinate types (as documented by a VarHandle factory method), {@code P1},
 102  * {@code P2} and {@code PN} are the first, second and the n'th access mode
 103  * parameters named {@code p1}, {@code p2} and {@code pn} respectively, and
 104  * {@code R} is the return type.
 105  *
 106  * For example, for the generic shape of {@code (CT : T)} the
 107  * {@link #compareAndSet} access mode method documents that its method
 108  * signature is of the form {@code (CT, T expectedValue, T newValue)boolean},
 109  * where the parameter types named {@code extendedValue} and {@code newValue}
 110  * are the access mode parameter types.  If the VarHandle accesses array
 111  * elements with a shape of say {@code (T[], int : T)} then the access mode
 112  * method type is {@code (T[], int, T, T)boolean}.
 113  *
 114  * <p>Access modes are grouped into the following categories:
 115  * <ul>
 116  * <li>read access modes that get the value of a variable under specified
 117  * memory ordering effects.
 118  * The set of corresponding access mode methods belonging to this group
 119  * consists of the methods
 120  * {@link #get get},
 121  * {@link #getVolatile getVolatile},
 122  * {@link #getAcquire getAcquire},
 123  * {@link #getOpaque getOpaque}.
 124  * <li>write access modes that set the value of a variable under specified
 125  * memory ordering effects.
 126  * The set of corresponding access mode methods belonging to this group
 127  * consists of the methods
 128  * {@link #set set},
 129  * {@link #setVolatile setVolatile},
 130  * {@link #setRelease setRelease},
 131  * {@link #setOpaque setOpaque}.
 132  * <li>atomic update access modes that, for example, atomically compare and set
 133  * the value of a variable under specified memory ordering effects.
 134  * The set of corresponding access mode methods belonging to this group
 135  * consists of the methods
 136  * {@link #compareAndSet compareAndSet},
 137  * {@link #weakCompareAndSet weakCompareAndSet},
 138  * {@link #weakCompareAndSetVolatile weakCompareAndSetVolatile},
 139  * {@link #weakCompareAndSetAcquire weakCompareAndSetAcquire},
 140  * {@link #weakCompareAndSetRelease weakCompareAndSetRelease},
 141  * {@link #compareAndExchangeAcquire compareAndExchangeAcquire},
 142  * {@link #compareAndExchangeVolatile compareAndExchangeVolatile},
 143  * {@link #compareAndExchangeRelease compareAndExchangeRelease},
 144  * {@link #getAndSet getAndSet}.
 145  * <li>numeric atomic update access modes that, for example, atomically get and
 146  * set with addition the value of a variable under specified memory ordering
 147  * effects.
 148  * The set of corresponding access mode methods belonging to this group
 149  * consists of the methods
 150  * {@link #getAndAdd getAndAdd},
 151  * {@link #addAndGet addAndGet}.
 152  * </ul>
 153  *
 154  * <p>Factory methods that produce or {@link java.lang.invoke.MethodHandles.Lookup
 155  * lookup} VarHandle instances document the set of access modes that are
 156  * supported, which may also include documenting restrictions based on the
 157  * variable type and whether a variable is read-only.  If an access mode is not
 158  * supported then the corresponding signature-polymorphic method will on
 159  * invocation throw an {@code UnsupportedOperationException}.  Factory methods
 160  * should document any additional undeclared exceptions that may be thrown by
 161  * access mode methods.
 162  * The {@link #get get} access mode is supported for all
 163  * VarHandle instances and the corresponding method never throws
 164  * {@code UnsupportedOperationException}.
 165  * If a VarHandle references a read-only variable (for example a {@code final}
 166  * field) then write, atomic update and numeric atomic update access modes are
 167  * not supported and corresponding methods throw
 168  * {@code UnsupportedOperationException}.
 169  * Read/write access modes (if supported), with the exception of
 170  * {@code get} and {@code set}, provide atomic access for
 171  * reference types and all primitive types.
 172  * Unless stated otherwise in the documentation of a factory method, the access
 173  * modes {@code get} and {@code set} (if supported) provide atomic access for
 174  * reference types and all primitives types, with the exception of {@code long}
 175  * and {@code double} on 32-bit platforms.
 176  *
 177  * <p>Access modes will override any memory ordering effects specified at
 178  * the declaration site of a variable.  For example, a VarHandle accessing a
 179  * a field using the {@code get} access mode will access the field as
 180  * specified <em>by its access mode</em> even if that field is declared
 181  * {@code volatile}.  When mixed access is performed extreme care should be
 182  * taken since the Java Memory Model may permit surprising results.
 183  *
 184  * <p>In addition to supporting access to variables under various access modes,
 185  * a set of static methods, referred to as memory fence methods, is also
 186  * provided for fine-grained control of memory ordering.
 187  *
 188  * The Java Language Specification permits other threads to observe operations
 189  * as if they were executed in orders different than are apparent in program
 190  * source code, subject to constraints arising, for example, from the use of
 191  * locks, {@code volatile} fields or VarHandles.  The static methods,
 192  * {@link #fullFence fullFence}, {@link #acquireFence acquireFence},
 193  * {@link #releaseFence releaseFence}, {@link #loadLoadFence loadLoadFence} and
 194  * {@link #storeStoreFence storeStoreFence}, can also be used to impose
 195  * constraints.  Their specifications, as is the case for certain access modes,
 196  * are phrased in terms of the lack of "reorderings" -- observable ordering
 197  * effects that might otherwise occur if the fence was not present.  More
 198  * precise phrasing of the specification of access mode methods and memory fence
 199  * methods may accompany future updates of the Java Language Specification.
 200  *
 201  * <h1>Compilation of an access mode's method</h1>
 202  * A Java method call expression naming an access mode method can invoke a
 203  * VarHandle from Java source code.  From the viewpoint of source code, these
 204  * methods can take any arguments and their polymorphic result (if expressed)
 205  * can be cast to any return type.  Formally this is accomplished by giving the
 206  * access mode methods variable arity {@code Object} arguments and
 207  * {@code Object} return types (if the return type is polymorphic), but they
 208  * have an additional quality called <em>signature polymorphism</em> which
 209  * connects this freedom of invocation directly to the JVM execution stack.
 210  * <p>
 211  * As is usual with virtual methods, source-level calls to access mode methods
 212  * compile to an {@code invokevirtual} instruction.  More unusually, the
 213  * compiler must record the actual argument types, and may not perform method
 214  * invocation conversions on the arguments.  Instead, it must generate
 215  * instructions to push them on the stack according to their own unconverted
 216  * types.  The VarHandle object itself will be pushed on the stack before the
 217  * arguments.  The compiler then generates an {@code invokevirtual} instruction
 218  * that invokes the access mode method with a symbolic type descriptor which
 219  * describes the argument and return types.
 220  * <p>
 221  * To issue a complete symbolic type descriptor, the compiler must also
 222  * determine the return type (if polymorphic).  This is based on a cast on the
 223  * method invocation expression, if there is one, or else {@code Object} if the
 224  * invocation is an expression, or else {@code void} if the invocation is a
 225  * statement.  The cast may be to a primitive type (but not {@code void}).
 226  * <p>
 227  * As a corner case, an uncasted {@code null} argument is given a symbolic type
 228  * descriptor of {@code java.lang.Void}.  The ambiguity with the type
 229  * {@code Void} is harmless, since there are no references of type {@code Void}
 230  * except the null reference.
 231  *
 232  *
 233  * <h1><a name="invoke">Invocation of an access mode's method</a></h1>
 234  * The first time an {@code invokevirtual} instruction is executed it is linked
 235  * by symbolically resolving the names in the instruction and verifying that
 236  * the method call is statically legal.  This also holds for calls to access mode
 237  * methods.  In this case, the symbolic type descriptor emitted by the compiler
 238  * is checked for correct syntax, and names it contains are resolved.  Thus, an
 239  * {@code invokevirtual} instruction which invokes an access mode method will
 240  * always link, as long as the symbolic type descriptor is syntactically
 241  * well-formed and the types exist.
 242  * <p>
 243  * When the {@code invokevirtual} is executed after linking, the receiving
 244  * VarHandle's access mode type is first checked by the JVM to ensure that it
 245  * matches the symbolic type descriptor.  If the type
 246  * match fails, it means that the access mode method which the caller is
 247  * invoking is not present on the individual VarHandle being invoked.
 248  *
 249  * <p>
 250  * Invocation of an access mode's signature-polymorphic method behaves as if an
 251  * invocation of {@link MethodHandle#invoke}, where the receiving method handle
 252  * is bound to a VarHandle instance and the access mode.  More specifically, the
 253  * following:
 254  * <pre> {@code
 255  * VarHandle vh = ..
 256  * R r = (R) vh.{access-mode}(p1, p2, ..., pN);
 257  * }</pre>
 258  * behaves as if (modulo the access mode methods do not declare throwing of
 259  * {@code Throwable}):
 260  * <pre> {@code
 261  * VarHandle vh = ..
 262  * MethodHandle mh = MethodHandles.varHandleExactInvoker(
 263  *                       VarHandle.AccessMode.{access-mode},
 264  *                       vh.accessModeType(VarHandle.AccessMode.{access-mode}));
 265  *
 266  * mh = mh.bindTo(vh);
 267  * R r = (R) mh.invoke(p1, p2, ..., pN)
 268  * }</pre>
 269  * or, more concisely, behaves as if:
 270  * <pre> {@code
 271  * VarHandle vh = ..
 272  * MethodHandle mh = vh.toMethodHandle(VarHandle.AccessMode.{access-mode});
 273  *
 274  * R r = (R) mh.invoke(p1, p2, ..., pN)
 275  * }</pre>
 276  * In terms of equivalent {@code invokevirtual} bytecode behaviour an access
 277  * mode method invocation is equivalent to:
 278  * <pre> {@code
 279  * MethodHandle mh = MethodHandles.lookup().findVirtual(
 280  *                       VarHandle.class,
 281  *                       VarHandle.AccessMode.{access-mode}.methodName(),
 282  *                       MethodType.methodType(R, p1, p2, ..., pN));
 283  *
 284  * R r = (R) mh.invokeExact(vh, p1, p2, ..., pN)
 285  * }</pre>
 286  * where the desired method type is the symbolic type descriptor and a
 287  * {@link MethodHandle#invokeExact} is performed, since before invocation of the
 288  * target, the handle will apply reference casts as necessary and box, unbox, or
 289  * widen primitive values, as if by {@link MethodHandle#asType asType} (see also
 290  * {@link MethodHandles#varHandleInvoker}).
 291  *
 292  * <h1>Invocation checking</h1>
 293  * In typical programs, VarHandle access mode type matching will usually
 294  * succeed.  But if a match fails, the JVM will throw a
 295  * {@link WrongMethodTypeException}.
 296  * <p>
 297  * Thus, an access mode type mismatch which might show up as a linkage error
 298  * in a statically typed program can show up as a dynamic
 299  * {@code WrongMethodTypeException} in a program which uses VarHandles.
 300  * <p>
 301  * Because access mode types contain "live" {@code Class} objects, method type
 302  * matching takes into account both type names and class loaders.
 303  * Thus, even if a VarHandle {@code VH} is created in one class loader
 304  * {@code L1} and used in another {@code L2}, VarHandle access mode method
 305  * calls are type-safe, because the caller's symbolic type descriptor, as
 306  * resolved in {@code L2}, is matched against the original callee method's
 307  * symbolic type descriptor, as resolved in {@code L1}.  The resolution in
 308  * {@code L1} happens when {@code VH} is created and its access mode types are
 309  * assigned, while the resolution in {@code L2} happens when the
 310  * {@code invokevirtual} instruction is linked.
 311  * <p>
 312  * Apart from type descriptor checks, a VarHandles's capability to
 313  * access it's variables is unrestricted.
 314  * If a VarHandle is formed on a non-public variable by a class that has access
 315  * to that variable, the resulting VarHandle can be used in any place by any
 316  * caller who receives a reference to it.
 317  * <p>
 318  * Unlike with the Core Reflection API, where access is checked every time a
 319  * reflective method is invoked, VarHandle access checking is performed
 320  * <a href="MethodHandles.Lookup.html#access">when the VarHandle is
 321  * created</a>.
 322  * Thus, VarHandles to non-public variables, or to variables in non-public
 323  * classes, should generally be kept secret.  They should not be passed to
 324  * untrusted code unless their use from the untrusted code would be harmless.
 325  *
 326  *
 327  * <h1>VarHandle creation</h1>
 328  * Java code can create a VarHandle that directly accesses any field that is
 329  * accessible to that code.  This is done via a reflective, capability-based
 330  * API called {@link java.lang.invoke.MethodHandles.Lookup
 331  * MethodHandles.Lookup}.
 332  * For example, a VarHandle for a non-static field can be obtained
 333  * from {@link java.lang.invoke.MethodHandles.Lookup#findVarHandle
 334  * Lookup.findVarHandle}.
 335  * There is also a conversion method from Core Reflection API objects,
 336  * {@link java.lang.invoke.MethodHandles.Lookup#unreflectVarHandle
 337  * Lookup.unreflectVarHandle}.
 338  * <p>
 339  * Access to protected field members is restricted to receivers only of the
 340  * accessing class, or one of its subclasses, and the accessing class must in
 341  * turn be a subclass (or package sibling) of the protected member's defining
 342  * class.  If a VarHandle refers to a protected non-static field of a declaring
 343  * class outside the current package, the receiver argument will be narrowed to
 344  * the type of the accessing class.
 345  *
 346  * <h1>Interoperation between VarHandles and the Core Reflection API</h1>
 347  * Using factory methods in the {@link java.lang.invoke.MethodHandles.Lookup
 348  * Lookup} API, any field represented by a Core Reflection API object
 349  * can be converted to a behaviorally equivalent VarHandle.
 350  * For example, a reflective {@link java.lang.reflect.Field Field} can
 351  * be converted to a VarHandle using
 352  * {@link java.lang.invoke.MethodHandles.Lookup#unreflectVarHandle
 353  * Lookup.unreflectVarHandle}.
 354  * The resulting VarHandles generally provide more direct and efficient
 355  * access to the underlying fields.
 356  * <p>
 357  * As a special case, when the Core Reflection API is used to view the
 358  * signature polymorphic access mode methods in this class, they appear as
 359  * ordinary non-polymorphic methods.  Their reflective appearance, as viewed by
 360  * {@link java.lang.Class#getDeclaredMethod Class.getDeclaredMethod},
 361  * is unaffected by their special status in this API.
 362  * For example, {@link java.lang.reflect.Method#getModifiers
 363  * Method.getModifiers}
 364  * will report exactly those modifier bits required for any similarly
 365  * declared method, including in this case {@code native} and {@code varargs}
 366  * bits.
 367  * <p>
 368  * As with any reflected method, these methods (when reflected) may be invoked
 369  * directly via {@link java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke},
 370  * via JNI, or indirectly via
 371  * {@link java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect}.
 372  * However, such reflective calls do not result in access mode method
 373  * invocations.  Such a call, if passed the required argument (a single one, of
 374  * type {@code Object[]}), will ignore the argument and will throw an
 375  * {@code UnsupportedOperationException}.
 376  * <p>
 377  * Since {@code invokevirtual} instructions can natively invoke VarHandle
 378  * access mode methods under any symbolic type descriptor, this reflective view
 379  * conflicts with the normal presentation of these methods via bytecodes.
 380  * Thus, these native methods, when reflectively viewed by
 381  * {@code Class.getDeclaredMethod}, may be regarded as placeholders only.
 382  * <p>
 383  * In order to obtain an invoker method for a particular access mode type,
 384  * use {@link java.lang.invoke.MethodHandles#varHandleExactInvoker} or
 385  * {@link java.lang.invoke.MethodHandles#varHandleInvoker}.  The
 386  * {@link java.lang.invoke.MethodHandles.Lookup#findVirtual Lookup.findVirtual}
 387  * API is also able to return a method handle to call an access mode method for
 388  * any specified access mode type and is equivalent in behaviour to
 389  * {@link java.lang.invoke.MethodHandles#varHandleInvoker}.
 390  *
 391  * <h1>Interoperation between VarHandles and Java generics</h1>
 392  * A VarHandle can be obtained for a variable, such as a a field, which is
 393  * declared with Java generic types.  As with the Core Reflection API, the
 394  * VarHandle's variable type will be constructed from the erasure of the
 395  * source-level type.  When a VarHandle access mode method is invoked, the
 396  * types
 397  * of its arguments or the return value cast type may be generic types or type
 398  * instances.  If this occurs, the compiler will replace those types by their
 399  * erasures when it constructs the symbolic type descriptor for the
 400  * {@code invokevirtual} instruction.
 401  *
 402  * @see MethodHandle
 403  * @see MethodHandles
 404  * @see MethodType
 405  * @since 9
 406  */
 407 public abstract class VarHandle {
 408     final VarForm vform;
 409 
 410     VarHandle(VarForm vform) {
 411         this.vform = vform;
 412     }
 413 
 414     RuntimeException unsupported() {
 415         return new UnsupportedOperationException();
 416     }
 417 
 418     // Plain accessors
 419 
 420     /**
 421      * Returns the value of a variable, with memory semantics of reading as
 422      * if the variable was declared non-{@code volatile}.  Commonly referred to
 423      * as plain read access.
 424      *
 425      * <p>The method signature is of the form {@code (CT)T}.
 426      *
 427      * <p>The symbolic type descriptor at the call site of {@code get}
 428      * must match the access mode type that is the result of calling
 429      * {@code accessModeType(VarHandle.AccessMode.GET)} on this VarHandle.
 430      *
 431      * <p>This access mode is supported by all VarHandle instances and never
 432      * throws {@code UnsupportedOperationException}.
 433      *
 434      * @param args the signature-polymorphic parameter list of the form
 435      * {@code (CT)}
 436      * , statically represented using varargs.
 437      * @return the signature-polymorphic result that is the value of the
 438      * variable
 439      * , statically represented using {@code Object}.
 440      * @throws WrongMethodTypeException if the access mode type is not
 441      * compatible with the caller's symbolic type descriptor.
 442      * @throws ClassCastException if the access mode type is compatible with the
 443      * caller's symbolic type descriptor, but a reference cast fails.
 444      */
 445     public final native
 446     @MethodHandle.PolymorphicSignature
 447     @HotSpotIntrinsicCandidate
 448     Object get(Object... args);
 449 
 450     /**
 451      * Sets the value of a variable to the {@code newValue}, with memory
 452      * semantics of setting as if the variable was declared non-{@code volatile}
 453      * and non-{@code final}.  Commonly referred to as plain write access.
 454      *
 455      * <p>The method signature is of the form {@code (CT, T newValue)void}
 456      *
 457      * <p>The symbolic type descriptor at the call site of {@code set}
 458      * must match the access mode type that is the result of calling
 459      * {@code accessModeType(VarHandle.AccessMode.SET)} on this VarHandle.
 460      *
 461      * @param args the signature-polymorphic parameter list of the form
 462      * {@code (CT, T newValue)}
 463      * , statically represented using varargs.
 464      * @throws UnsupportedOperationException if the access mode is unsupported
 465      * for this VarHandle.
 466      * @throws WrongMethodTypeException if the access mode type is not
 467      * compatible with the caller's symbolic type descriptor.
 468      * @throws ClassCastException if the access mode type is compatible with the
 469      * caller's symbolic type descriptor, but a reference cast fails.
 470      */
 471     public final native
 472     @MethodHandle.PolymorphicSignature
 473     @HotSpotIntrinsicCandidate
 474     void set(Object... args);
 475 
 476 
 477     // Volatile accessors
 478 
 479     /**
 480      * Returns the value of a variable, with memory semantics of reading as if
 481      * the variable was declared {@code volatile}.
 482      *
 483      * <p>The method signature is of the form {@code (CT)T}.
 484      *
 485      * <p>The symbolic type descriptor at the call site of {@code getVolatile}
 486      * must match the access mode type that is the result of calling
 487      * {@code accessModeType(VarHandle.AccessMode.GET_VOLATILE)} on this
 488      * VarHandle.
 489      *
 490      * @param args the signature-polymorphic parameter list of the form
 491      * {@code (CT)}
 492      * , statically represented using varargs.
 493      * @return the signature-polymorphic result that is the value of the
 494      * variable
 495      * , statically represented using {@code Object}.
 496      * @throws UnsupportedOperationException if the access mode is unsupported
 497      * for this VarHandle.
 498      * @throws WrongMethodTypeException if the access mode type is not
 499      * compatible with the caller's symbolic type descriptor.
 500      * @throws ClassCastException if the access mode type is compatible with the
 501      * caller's symbolic type descriptor, but a reference cast fails.
 502      */
 503     public final native
 504     @MethodHandle.PolymorphicSignature
 505     @HotSpotIntrinsicCandidate
 506     Object getVolatile(Object... args);
 507 
 508     /**
 509      * Sets the value of a variable to the {@code newValue}, with memory
 510      * semantics of setting as if the variable was declared {@code volatile}.
 511      *
 512      * <p>The method signature is of the form {@code (CT, T newValue)void}.
 513      *
 514      * <p>The symbolic type descriptor at the call site of {@code setVolatile}
 515      * must match the access mode type that is the result of calling
 516      * {@code accessModeType(VarHandle.AccessMode.SET_VOLATILE)} on this
 517      * VarHandle.
 518      *
 519      * @apiNote
 520      * Ignoring the many semantic differences from C and C++, this method has
 521      * memory ordering effects compatible with {@code memory_order_seq_cst}.
 522      *
 523      * @param args the signature-polymorphic parameter list of the form
 524      * {@code (CT, T newValue)}
 525      * , statically represented using varargs.
 526      * @throws UnsupportedOperationException if the access mode is unsupported
 527      * for this VarHandle.
 528      * @throws WrongMethodTypeException if the access mode type is not
 529      * compatible with the caller's symbolic type descriptor.
 530      * @throws ClassCastException if the access mode type is compatible with the
 531      * caller's symbolic type descriptor, but a reference cast fails.
 532      */
 533     public final native
 534     @MethodHandle.PolymorphicSignature
 535     @HotSpotIntrinsicCandidate
 536     void setVolatile(Object... args);
 537 
 538 
 539     /**
 540      * Returns the value of a variable, accessed in program order, but with no
 541      * assurance of memory ordering effects with respect to other threads.
 542      *
 543      * <p>The method signature is of the form {@code (CT)T}.
 544      *
 545      * <p>The symbolic type descriptor at the call site of {@code getOpaque}
 546      * must match the access mode type that is the result of calling
 547      * {@code accessModeType(VarHandle.AccessMode.GET_OPAQUE)} on this
 548      * VarHandle.
 549      *
 550      * @param args the signature-polymorphic parameter list of the form
 551      * {@code (CT)}
 552      * , statically represented using varargs.
 553      * @return the signature-polymorphic result that is the value of the
 554      * variable
 555      * , statically represented using {@code Object}.
 556      * @throws UnsupportedOperationException if the access mode is unsupported
 557      * for this VarHandle.
 558      * @throws WrongMethodTypeException if the access mode type is not
 559      * compatible with the caller's symbolic type descriptor.
 560      * @throws ClassCastException if the access mode type is compatible with the
 561      * caller's symbolic type descriptor, but a reference cast fails.
 562      */
 563     public final native
 564     @MethodHandle.PolymorphicSignature
 565     @HotSpotIntrinsicCandidate
 566     Object getOpaque(Object... args);
 567 
 568     /**
 569      * Sets the value of a variable to the {@code newValue}, in program order,
 570      * but with no assurance of memory ordering effects with respect to other
 571      * threads.
 572      *
 573      * <p>The method signature is of the form {@code (CT, T newValue)void}.
 574      *
 575      * <p>The symbolic type descriptor at the call site of {@code setOpaque}
 576      * must match the access mode type that is the result of calling
 577      * {@code accessModeType(VarHandle.AccessMode.SET_OPAQUE)} on this
 578      * VarHandle.
 579      *
 580      * @param args the signature-polymorphic parameter list of the form
 581      * {@code (CT, T newValue)}
 582      * , statically represented using varargs.
 583      * @throws UnsupportedOperationException if the access mode is unsupported
 584      * for this VarHandle.
 585      * @throws WrongMethodTypeException if the access mode type is not
 586      * compatible with the caller's symbolic type descriptor.
 587      * @throws ClassCastException if the access mode type is compatible with the
 588      * caller's symbolic type descriptor, but a reference cast fails.
 589      */
 590     public final native
 591     @MethodHandle.PolymorphicSignature
 592     @HotSpotIntrinsicCandidate
 593     void setOpaque(Object... args);
 594 
 595 
 596     // Lazy accessors
 597 
 598     /**
 599      * Returns the value of a variable, and ensures that subsequent loads and
 600      * stores are not reordered before this access.
 601      *
 602      * <p>The method signature is of the form {@code (CT)T}.
 603      *
 604      * <p>The symbolic type descriptor at the call site of {@code getAcquire}
 605      * must match the access mode type that is the result of calling
 606      * {@code accessModeType(VarHandle.AccessMode.GET_ACQUIRE)} on this
 607      * VarHandle.
 608      *
 609      * @apiNote
 610      * Ignoring the many semantic differences from C and C++, this method has
 611      * memory ordering effects compatible with {@code memory_order_acquire}
 612      * ordering.
 613      *
 614      * @param args the signature-polymorphic parameter list of the form
 615      * {@code (CT)}
 616      * , statically represented using varargs.
 617      * @return the signature-polymorphic result that is the value of the
 618      * variable
 619      * , statically represented using {@code Object}.
 620      * @throws UnsupportedOperationException if the access mode is unsupported
 621      * for this VarHandle.
 622      * @throws WrongMethodTypeException if the access mode type is not
 623      * compatible with the caller's symbolic type descriptor.
 624      * @throws ClassCastException if the access mode type is compatible with the
 625      * caller's symbolic type descriptor, but a reference cast fails.
 626      */
 627     public final native
 628     @MethodHandle.PolymorphicSignature
 629     @HotSpotIntrinsicCandidate
 630     Object getAcquire(Object... args);
 631 
 632     /**
 633      * Sets the value of a variable to the {@code newValue}, and ensures that
 634      * prior loads and stores are not reordered after this access.
 635      *
 636      * <p>The method signature is of the form {@code (CT, T newValue)void}.
 637      *
 638      * <p>The symbolic type descriptor at the call site of {@code setRelease}
 639      * must match the access mode type that is the result of calling
 640      * {@code accessModeType(VarHandle.AccessMode.SET_RELEASE)} on this
 641      * VarHandle.
 642      *
 643      * @apiNote
 644      * Ignoring the many semantic differences from C and C++, this method has
 645      * memory ordering effects compatible with {@code memory_order_release}
 646      * ordering.
 647      *
 648      * @param args the signature-polymorphic parameter list of the form
 649      * {@code (CT, T newValue)}
 650      * , statically represented using varargs.
 651      * @throws UnsupportedOperationException if the access mode is unsupported
 652      * for this VarHandle.
 653      * @throws WrongMethodTypeException if the access mode type is not
 654      * compatible with the caller's symbolic type descriptor.
 655      * @throws ClassCastException if the access mode type is compatible with the
 656      * caller's symbolic type descriptor, but a reference cast fails.
 657      */
 658     public final native
 659     @MethodHandle.PolymorphicSignature
 660     @HotSpotIntrinsicCandidate
 661     void setRelease(Object... args);
 662 
 663 
 664     // Compare and set accessors
 665 
 666     /**
 667      * Atomically sets the value of a variable to the {@code newValue} with the
 668      * memory semantics of {@link #setVolatile} if the variable's current value,
 669      * referred to as the <em>witness value</em>, {@code ==} the
 670      * {@code expectedValue}, as accessed with the memory semantics of
 671      * {@link #getVolatile}.
 672      *
 673      * <p>The method signature is of the form {@code (CT, T expectedValue, T newValue)boolean}.
 674      *
 675      * <p>The symbolic type descriptor at the call site of {@code
 676      * compareAndSet} must match the access mode type that is the result of
 677      * calling {@code accessModeType(VarHandle.AccessMode.COMPARE_AND_SET)} on
 678      * this VarHandle.
 679      *
 680      * @param args the signature-polymorphic parameter list of the form
 681      * {@code (CT, T expectedValue, T newValue)}
 682      * , statically represented using varargs.
 683      * @return {@code true} if successful, otherwise {@code false} if the
 684      * witness value was not the same as the {@code expectedValue}.
 685      * @throws UnsupportedOperationException if the access mode is unsupported
 686      * for this VarHandle.
 687      * @throws WrongMethodTypeException if the access mode type is not
 688      * compatible with the caller's symbolic type descriptor.
 689      * @throws ClassCastException if the access mode type is compatible with the
 690      * caller's symbolic type descriptor, but a reference cast fails.
 691      * @see #setVolatile(Object...)
 692      * @see #getVolatile(Object...)
 693      */
 694     public final native
 695     @MethodHandle.PolymorphicSignature
 696     @HotSpotIntrinsicCandidate
 697     boolean compareAndSet(Object... args);
 698 
 699     /**
 700      * Atomically sets the value of a variable to the {@code newValue} with the
 701      * memory semantics of {@link #setVolatile} if the variable's current value,
 702      * referred to as the <em>witness value</em>, {@code ==} the
 703      * {@code expectedValue}, as accessed with the memory semantics of
 704      * {@link #getVolatile}.
 705      *
 706      * <p>The method signature is of the form {@code (CT, T expectedValue, T newValue)T}.
 707      *
 708      * <p>The symbolic type descriptor at the call site of {@code
 709      * compareAndExchangeVolatile}
 710      * must match the access mode type that is the result of calling
 711      * {@code accessModeType(VarHandle.AccessMode.COMPARE_AND_EXCHANGE_VOLATILE)}
 712      * on this VarHandle.
 713      *
 714      * @param args the signature-polymorphic parameter list of the form
 715      * {@code (CT, T expectedValue, T newValue)}
 716      * , statically represented using varargs.
 717      * @return the signature-polymorphic result that is the witness value, which
 718      * will be the same as the {@code expectedValue} if successful
 719      * , statically represented using {@code Object}.
 720      * @throws UnsupportedOperationException if the access mode is unsupported
 721      * for this VarHandle.
 722      * @throws WrongMethodTypeException if the access mode type is not
 723      * compatible with the caller's symbolic type descriptor.
 724      * @throws ClassCastException if the access mode type is compatible with the
 725      * caller's symbolic type descriptor, but a reference cast fails.
 726      * @see #setVolatile(Object...)
 727      * @see #getVolatile(Object...)
 728      */
 729     public final native
 730     @MethodHandle.PolymorphicSignature
 731     @HotSpotIntrinsicCandidate
 732     Object compareAndExchangeVolatile(Object... args);
 733 
 734     /**
 735      * Atomically sets the value of a variable to the {@code newValue} with the
 736      * memory semantics of {@link #set} if the variable's current value,
 737      * referred to as the <em>witness value</em>, {@code ==} the
 738      * {@code expectedValue}, as accessed with the memory semantics of
 739      * {@link #getAcquire}.
 740      *
 741      * <p>The method signature is of the form {@code (CT, T expectedValue, T newValue)T}.
 742      *
 743      * <p>The symbolic type descriptor at the call site of {@code
 744      * compareAndExchangeAcquire}
 745      * must match the access mode type that is the result of calling
 746      * {@code accessModeType(VarHandle.AccessMode.COMPARE_AND_EXCHANGE_ACQUIRE)} on
 747      * this VarHandle.
 748      *
 749      * @param args the signature-polymorphic parameter list of the form
 750      * {@code (CT, T expectedValue, T newValue)}
 751      * , statically represented using varargs.
 752      * @return the signature-polymorphic result that is the witness value, which
 753      * will be the same as the {@code expectedValue} if successful
 754      * , statically represented using {@code Object}.
 755      * @throws UnsupportedOperationException if the access mode is unsupported
 756      * for this VarHandle.
 757      * @throws WrongMethodTypeException if the access mode type is not
 758      * compatible with the caller's symbolic type descriptor.
 759      * @throws ClassCastException if the access mode type is compatible with the
 760      * caller's symbolic type descriptor, but a reference cast fails.
 761      * @see #set(Object...)
 762      * @see #getAcquire(Object...)
 763      */
 764     public final native
 765     @MethodHandle.PolymorphicSignature
 766     @HotSpotIntrinsicCandidate
 767     Object compareAndExchangeAcquire(Object... args);
 768 
 769     /**
 770      * Atomically sets the value of a variable to the {@code newValue} with the
 771      * memory semantics of {@link #setRelease} if the variable's current value,
 772      * referred to as the <em>witness value</em>, {@code ==} the
 773      * {@code expectedValue}, as accessed with the memory semantics of
 774      * {@link #get}.
 775      *
 776      * <p>The method signature is of the form {@code (CT, T expectedValue, T newValue)T}.
 777      *
 778      * <p>The symbolic type descriptor at the call site of {@code
 779      * compareAndExchangeRelease}
 780      * must match the access mode type that is the result of calling
 781      * {@code accessModeType(VarHandle.AccessMode.COMPARE_AND_EXCHANGE_RELEASE)}
 782      * on this VarHandle.
 783      *
 784      * @param args the signature-polymorphic parameter list of the form
 785      * {@code (CT, T expectedValue, T newValue)}
 786      * , statically represented using varargs.
 787      * @return the signature-polymorphic result that is the witness value, which
 788      * will be the same as the {@code expectedValue} if successful
 789      * , statically represented using {@code Object}.
 790      * @throws UnsupportedOperationException if the access mode is unsupported
 791      * for this VarHandle.
 792      * @throws WrongMethodTypeException if the access mode type is not
 793      * compatible with the caller's symbolic type descriptor.
 794      * @throws ClassCastException if the access mode type is compatible with the
 795      * caller's symbolic type descriptor, but a reference cast fails.
 796      * @see #setRelease(Object...)
 797      * @see #get(Object...)
 798      */
 799     public final native
 800     @MethodHandle.PolymorphicSignature
 801     @HotSpotIntrinsicCandidate
 802     Object compareAndExchangeRelease(Object... args);
 803 
 804     // Weak (spurious failures allowed)
 805 
 806     /**
 807      * Possibly atomically sets the value of a variable to the {@code newValue}
 808      * with the semantics of {@link #set} if the variable's current value,
 809      * referred to as the <em>witness value</em>, {@code ==} the
 810      * {@code expectedValue}, as accessed with the memory semantics of
 811      * {@link #get}.
 812      *
 813      * <p>This operation may fail spuriously (typically, due to memory
 814      * contention) even if the witness value does match the expected value.
 815      *
 816      * <p>The method signature is of the form {@code (CT, T expectedValue, T newValue)boolean}.
 817      *
 818      * <p>The symbolic type descriptor at the call site of {@code
 819      * weakCompareAndSet} must match the access mode type that is the result of
 820      * calling {@code accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET)}
 821      * on this VarHandle.
 822      *
 823      * @param args the signature-polymorphic parameter list of the form
 824      * {@code (CT, T expectedValue, T newValue)}
 825      * , statically represented using varargs.
 826      * @return {@code true} if successful, otherwise {@code false} if the
 827      * witness value was not the same as the {@code expectedValue} or if this
 828      * operation spuriously failed.
 829      * @throws UnsupportedOperationException if the access mode is unsupported
 830      * for this VarHandle.
 831      * @throws WrongMethodTypeException if the access mode type is not
 832      * compatible with the caller's symbolic type descriptor.
 833      * @throws ClassCastException if the access mode type is compatible with the
 834      * caller's symbolic type descriptor, but a reference cast fails.
 835      * @see #set(Object...)
 836      * @see #get(Object...)
 837      */
 838     public final native
 839     @MethodHandle.PolymorphicSignature
 840     @HotSpotIntrinsicCandidate
 841     boolean weakCompareAndSet(Object... args);
 842 
 843     /**
 844      * Possibly atomically sets the value of a variable to the {@code newValue}
 845      * with the memory semantics of {@link #setVolatile} if the variable's
 846      * current value, referred to as the <em>witness value</em>, {@code ==} the
 847      * {@code expectedValue}, as accessed with the memory semantics of
 848      * {@link #getVolatile}.
 849      *
 850      * <p>This operation may fail spuriously (typically, due to memory
 851      * contention) even if the witness value does match the expected value.
 852      *
 853      * <p>The method signature is of the form {@code (CT, T expectedValue, T newValue)boolean}.
 854      *
 855      * <p>The symbolic type descriptor at the call site of {@code
 856      * weakCompareAndSetVolatile} must match the access mode type that is the
 857      * result of calling {@code accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET_VOLATILE)}
 858      * on this VarHandle.
 859      *
 860      * @param args the signature-polymorphic parameter list of the form
 861      * {@code (CT, T expectedValue, T newValue)}
 862      * , statically represented using varargs.
 863      * @return {@code true} if successful, otherwise {@code false} if the
 864      * witness value was not the same as the {@code expectedValue} or if this
 865      * operation spuriously failed.
 866      * @throws UnsupportedOperationException if the access mode is unsupported
 867      * for this VarHandle.
 868      * @throws WrongMethodTypeException if the access mode type is not
 869      * compatible with the caller's symbolic type descriptor.
 870      * @throws ClassCastException if the access mode type is compatible with the
 871      * caller's symbolic type descriptor, but a reference cast fails.
 872      * @see #setVolatile(Object...)
 873      * @see #getVolatile(Object...)
 874      */
 875     public final native
 876     @MethodHandle.PolymorphicSignature
 877     @HotSpotIntrinsicCandidate
 878     boolean weakCompareAndSetVolatile(Object... args);
 879 
 880     /**
 881      * Possibly atomically sets the value of a variable to the {@code newValue}
 882      * with the semantics of {@link #set} if the variable's current value,
 883      * referred to as the <em>witness value</em>, {@code ==} the
 884      * {@code expectedValue}, as accessed with the memory semantics of
 885      * {@link #getAcquire}.
 886      *
 887      * <p>This operation may fail spuriously (typically, due to memory
 888      * contention) even if the witness value does match the expected value.
 889      *
 890      * <p>The method signature is of the form {@code (CT, T expectedValue, T newValue)boolean}.
 891      *
 892      * <p>The symbolic type descriptor at the call site of {@code
 893      * weakCompareAndSetAcquire}
 894      * must match the access mode type that is the result of calling
 895      * {@code accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET_ACQUIRE)}
 896      * on this VarHandle.
 897      *
 898      * @param args the signature-polymorphic parameter list of the form
 899      * {@code (CT, T expectedValue, T newValue)}
 900      * , statically represented using varargs.
 901      * @return {@code true} if successful, otherwise {@code false} if the
 902      * witness value was not the same as the {@code expectedValue} or if this
 903      * operation spuriously failed.
 904      * @throws UnsupportedOperationException if the access mode is unsupported
 905      * for this VarHandle.
 906      * @throws WrongMethodTypeException if the access mode type is not
 907      * compatible with the caller's symbolic type descriptor.
 908      * @throws ClassCastException if the access mode type is compatible with the
 909      * caller's symbolic type descriptor, but a reference cast fails.
 910      * @see #set(Object...)
 911      * @see #getAcquire(Object...)
 912      */
 913     public final native
 914     @MethodHandle.PolymorphicSignature
 915     @HotSpotIntrinsicCandidate
 916     boolean weakCompareAndSetAcquire(Object... args);
 917 
 918     /**
 919      * Possibly atomically sets the value of a variable to the {@code newValue}
 920      * with the semantics of {@link #setRelease} if the variable's current
 921      * value, referred to as the <em>witness value</em>, {@code ==} the
 922      * {@code expectedValue}, as accessed with the memory semantics of
 923      * {@link #get}.
 924      *
 925      * <p>This operation may fail spuriously (typically, due to memory
 926      * contention) even if the witness value does match the expected value.
 927      *
 928      * <p>The method signature is of the form {@code (CT, T expectedValue, T newValue)boolean}.
 929      *
 930      * <p>The symbolic type descriptor at the call site of {@code
 931      * weakCompareAndSetRelease}
 932      * must match the access mode type that is the result of calling
 933      * {@code accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET_RELEASE)}
 934      * on this VarHandle.
 935      *
 936      * @param args the signature-polymorphic parameter list of the form
 937      * {@code (CT, T expectedValue, T newValue)}
 938      * , statically represented using varargs.
 939      * @return {@code true} if successful, otherwise {@code false} if the
 940      * witness value was not the same as the {@code expectedValue} or if this
 941      * operation spuriously failed.
 942      * @throws UnsupportedOperationException if the access mode is unsupported
 943      * for this VarHandle.
 944      * @throws WrongMethodTypeException if the access mode type is not
 945      * compatible with the caller's symbolic type descriptor.
 946      * @throws ClassCastException if the access mode type is compatible with the
 947      * caller's symbolic type descriptor, but a reference cast fails.
 948      * @see #setRelease(Object...)
 949      * @see #get(Object...)
 950      */
 951     public final native
 952     @MethodHandle.PolymorphicSignature
 953     @HotSpotIntrinsicCandidate
 954     boolean weakCompareAndSetRelease(Object... args);
 955 
 956     /**
 957      * Atomically sets the value of a variable to the {@code newValue} with the
 958      * memory semantics of {@link #setVolatile} and returns the variable's
 959      * previous value, as accessed with the memory semantics of
 960      * {@link #getVolatile}.
 961      *
 962      * <p>The method signature is of the form {@code (CT, T newValue)T}.
 963      *
 964      * <p>The symbolic type descriptor at the call site of {@code getAndSet}
 965      * must match the access mode type that is the result of calling
 966      * {@code accessModeType(VarHandle.AccessMode.GET_AND_SET)} on this
 967      * VarHandle.
 968      *
 969      * @param args the signature-polymorphic parameter list of the form
 970      * {@code (CT, T newValue)}
 971      * , statically represented using varargs.
 972      * @return the signature-polymorphic result that is the previous value of
 973      * the variable
 974      * , statically represented using {@code Object}.
 975      * @throws UnsupportedOperationException if the access mode is unsupported
 976      * for this VarHandle.
 977      * @throws WrongMethodTypeException if the access mode type is not
 978      * compatible with the caller's symbolic type descriptor.
 979      * @throws ClassCastException if the access mode type is compatible with the
 980      * caller's symbolic type descriptor, but a reference cast fails.
 981      * @see #setVolatile(Object...)
 982      * @see #getVolatile(Object...)
 983      */
 984     public final native
 985     @MethodHandle.PolymorphicSignature
 986     @HotSpotIntrinsicCandidate
 987     Object getAndSet(Object... args);
 988 
 989 
 990     // Primitive adders
 991     // Throw UnsupportedOperationException for refs
 992 
 993     /**
 994      * Atomically adds the {@code value} to the current value of a variable with
 995      * the memory semantics of {@link #setVolatile}, and returns the variable's
 996      * previous value, as accessed with the memory semantics of
 997      * {@link #getVolatile}.
 998      *
 999      * <p>The method signature is of the form {@code (CT, T value)T}.
1000      *
1001      * <p>The symbolic type descriptor at the call site of {@code getAndAdd}
1002      * must match the access mode type that is the result of calling
1003      * {@code accessModeType(VarHandle.AccessMode.GET_AND_ADD)} on this
1004      * VarHandle.
1005      *
1006      * @param args the signature-polymorphic parameter list of the form
1007      * {@code (CT, T value)}
1008      * , statically represented using varargs.
1009      * @return the signature-polymorphic result that is the previous value of
1010      * the variable
1011      * , statically represented using {@code Object}.
1012      * @throws UnsupportedOperationException if the access mode is unsupported
1013      * for this VarHandle.
1014      * @throws WrongMethodTypeException if the access mode type is not
1015      * compatible with the caller's symbolic type descriptor.
1016      * @throws ClassCastException if the access mode type is compatible with the
1017      * caller's symbolic type descriptor, but a reference cast fails.
1018      * @see #setVolatile(Object...)
1019      * @see #getVolatile(Object...)
1020      */
1021     public final native
1022     @MethodHandle.PolymorphicSignature
1023     @HotSpotIntrinsicCandidate
1024     Object getAndAdd(Object... args);
1025 
1026     /**
1027      * Atomically adds the {@code value} to the current value of a variable with
1028      * the memory semantics of {@link #setVolatile}, and returns the variable's
1029      * current (updated) value, as accessed with the memory semantics of
1030      * {@link #getVolatile}.
1031      *
1032      * <p>The method signature is of the form {@code (CT, T value)T}.
1033      *
1034      * <p>The symbolic type descriptor at the call site of {@code addAndGet}
1035      * must match the access mode type that is the result of calling
1036      * {@code accessModeType(VarHandle.AccessMode.ADD_AND_GET)} on this
1037      * VarHandle.
1038      *
1039      * @param args the signature-polymorphic parameter list of the form
1040      * {@code (CT, T value)}
1041      * , statically represented using varargs.
1042      * @return the signature-polymorphic result that is the current value of
1043      * the variable
1044      * , statically represented using {@code Object}.
1045      * @throws UnsupportedOperationException if the access mode is unsupported
1046      * for this VarHandle.
1047      * @throws WrongMethodTypeException if the access mode type is not
1048      * compatible with the caller's symbolic type descriptor.
1049      * @throws ClassCastException if the access mode type is compatible with the
1050      * caller's symbolic type descriptor, but a reference cast fails.
1051      * @see #setVolatile(Object...)
1052      * @see #getVolatile(Object...)
1053      */
1054     public final native
1055     @MethodHandle.PolymorphicSignature
1056     @HotSpotIntrinsicCandidate
1057     Object addAndGet(Object... args);
1058 
1059     enum AccessType {
1060         GET(Object.class) {
1061             @Override
1062             MethodType accessModeType(Class<?> receiver, Class<?> value,
1063                                       Class<?>... intermediate) {
1064                 Class<?>[] ps =  allocateParameters(0, receiver, intermediate);
1065                 fillParameters(ps, receiver, intermediate);
1066                 return MethodType.methodType(value, ps);
1067             }
1068         },
1069         SET(void.class) {
1070             @Override
1071             MethodType accessModeType(Class<?> receiver, Class<?> value,
1072                                       Class<?>... intermediate) {
1073                 Class<?>[] ps =  allocateParameters(1, receiver, intermediate);
1074                 int i = fillParameters(ps, receiver, intermediate);
1075                 ps[i] = value;
1076                 return MethodType.methodType(void.class, ps);
1077             }
1078         },
1079         COMPARE_AND_SWAP(boolean.class) {
1080             @Override
1081             MethodType accessModeType(Class<?> receiver, Class<?> value,
1082                                       Class<?>... intermediate) {
1083                 Class<?>[] ps =  allocateParameters(2, receiver, intermediate);
1084                 int i = fillParameters(ps, receiver, intermediate);
1085                 ps[i++] = value;
1086                 ps[i] = value;
1087                 return MethodType.methodType(boolean.class, ps);
1088             }
1089         },
1090         COMPARE_AND_EXCHANGE(Object.class) {
1091             @Override
1092             MethodType accessModeType(Class<?> receiver, Class<?> value,
1093                                       Class<?>... intermediate) {
1094                 Class<?>[] ps =  allocateParameters(2, receiver, intermediate);
1095                 int i = fillParameters(ps, receiver, intermediate);
1096                 ps[i++] = value;
1097                 ps[i] = value;
1098                 return MethodType.methodType(value, ps);
1099             }
1100         },
1101         GET_AND_UPDATE(Object.class) {
1102             @Override
1103             MethodType accessModeType(Class<?> receiver, Class<?> value,
1104                                       Class<?>... intermediate) {
1105                 Class<?>[] ps =  allocateParameters(1, receiver, intermediate);
1106                 int i = fillParameters(ps, receiver, intermediate);
1107                 ps[i] = value;
1108                 return MethodType.methodType(value, ps);
1109             }
1110         };
1111 
1112         final Class<?> returnType;
1113         final boolean isMonomorphicInReturnType;
1114 
1115         AccessType(Class<?> returnType) {
1116             this.returnType = returnType;
1117             isMonomorphicInReturnType = returnType != Object.class;
1118         }
1119 
1120         abstract MethodType accessModeType(Class<?> receiver, Class<?> value,
1121                                            Class<?>... intermediate);
1122 
1123         private static Class<?>[] allocateParameters(int values,
1124                                                      Class<?> receiver, Class<?>... intermediate) {
1125             int size = ((receiver != null) ? 1 : 0) + intermediate.length + values;
1126             return new Class<?>[size];
1127         }
1128 
1129         private static int fillParameters(Class<?>[] ps,
1130                                           Class<?> receiver, Class<?>... intermediate) {
1131             int i = 0;
1132             if (receiver != null)
1133                 ps[i++] = receiver;
1134             for (int j = 0; j < intermediate.length; j++)
1135                 ps[i++] = intermediate[j];
1136             return i;
1137         }
1138     }
1139 
1140     /**
1141      * The set of access modes that specify how a variable, referenced by a
1142      * VarHandle, is accessed.
1143      */
1144     public enum AccessMode {
1145         /**
1146          * The access mode whose access is specified by the corresponding
1147          * method
1148          * {@link VarHandle#get VarHandle.get}
1149          */
1150         GET("get", AccessType.GET),
1151         /**
1152          * The access mode whose access is specified by the corresponding
1153          * method
1154          * {@link VarHandle#set VarHandle.set}
1155          */
1156         SET("set", AccessType.SET),
1157         /**
1158          * The access mode whose access is specified by the corresponding
1159          * method
1160          * {@link VarHandle#getVolatile VarHandle.getVolatile}
1161          */
1162         GET_VOLATILE("getVolatile", AccessType.GET),
1163         /**
1164          * The access mode whose access is specified by the corresponding
1165          * method
1166          * {@link VarHandle#setVolatile VarHandle.setVolatile}
1167          */
1168         SET_VOLATILE("setVolatile", AccessType.SET),
1169         /**
1170          * The access mode whose access is specified by the corresponding
1171          * method
1172          * {@link VarHandle#getAcquire VarHandle.getAcquire}
1173          */
1174         GET_ACQUIRE("getAcquire", AccessType.GET),
1175         /**
1176          * The access mode whose access is specified by the corresponding
1177          * method
1178          * {@link VarHandle#setRelease VarHandle.setRelease}
1179          */
1180         SET_RELEASE("setRelease", AccessType.SET),
1181         /**
1182          * The access mode whose access is specified by the corresponding
1183          * method
1184          * {@link VarHandle#getOpaque VarHandle.getOpaque}
1185          */
1186         GET_OPAQUE("getOpaque", AccessType.GET),
1187         /**
1188          * The access mode whose access is specified by the corresponding
1189          * method
1190          * {@link VarHandle#setOpaque VarHandle.setOpaque}
1191          */
1192         SET_OPAQUE("setOpaque", AccessType.SET),
1193         /**
1194          * The access mode whose access is specified by the corresponding
1195          * method
1196          * {@link VarHandle#compareAndSet VarHandle.compareAndSet}
1197          */
1198         COMPARE_AND_SET("compareAndSet", AccessType.COMPARE_AND_SWAP),
1199         /**
1200          * The access mode whose access is specified by the corresponding
1201          * method
1202          * {@link VarHandle#compareAndExchangeVolatile VarHandle.compareAndExchangeVolatile}
1203          */
1204         COMPARE_AND_EXCHANGE_VOLATILE("compareAndExchangeVolatile", AccessType.COMPARE_AND_EXCHANGE),
1205         /**
1206          * The access mode whose access is specified by the corresponding
1207          * method
1208          * {@link VarHandle#compareAndExchangeAcquire VarHandle.compareAndExchangeAcquire}
1209          */
1210         COMPARE_AND_EXCHANGE_ACQUIRE("compareAndExchangeAcquire", AccessType.COMPARE_AND_EXCHANGE),
1211         /**
1212          * The access mode whose access is specified by the corresponding
1213          * method
1214          * {@link VarHandle#compareAndExchangeRelease VarHandle.compareAndExchangeRelease}
1215          */
1216         COMPARE_AND_EXCHANGE_RELEASE("compareAndExchangeRelease", AccessType.COMPARE_AND_EXCHANGE),
1217         /**
1218          * The access mode whose access is specified by the corresponding
1219          * method
1220          * {@link VarHandle#weakCompareAndSet VarHandle.weakCompareAndSet}
1221          */
1222         WEAK_COMPARE_AND_SET("weakCompareAndSet", AccessType.COMPARE_AND_SWAP),
1223         /**
1224          * The access mode whose access is specified by the corresponding
1225          * method
1226          * {@link VarHandle#weakCompareAndSetVolatile VarHandle.weakCompareAndSetVolatile}
1227          */
1228         WEAK_COMPARE_AND_SET_VOLATILE("weakCompareAndSetVolatile", AccessType.COMPARE_AND_SWAP),
1229         /**
1230          * The access mode whose access is specified by the corresponding
1231          * method
1232          * {@link VarHandle#weakCompareAndSetAcquire VarHandle.weakCompareAndSetAcquire}
1233          */
1234         WEAK_COMPARE_AND_SET_ACQUIRE("weakCompareAndSetAcquire", AccessType.COMPARE_AND_SWAP),
1235         /**
1236          * The access mode whose access is specified by the corresponding
1237          * method
1238          * {@link VarHandle#weakCompareAndSetRelease VarHandle.weakCompareAndSetRelease}
1239          */
1240         WEAK_COMPARE_AND_SET_RELEASE("weakCompareAndSetRelease", AccessType.COMPARE_AND_SWAP),
1241         /**
1242          * The access mode whose access is specified by the corresponding
1243          * method
1244          * {@link VarHandle#getAndSet VarHandle.getAndSet}
1245          */
1246         GET_AND_SET("getAndSet", AccessType.GET_AND_UPDATE),
1247         /**
1248          * The access mode whose access is specified by the corresponding
1249          * method
1250          * {@link VarHandle#getAndAdd VarHandle.getAndAdd}
1251          */
1252         GET_AND_ADD("getAndAdd", AccessType.GET_AND_UPDATE),
1253         /**
1254          * The access mode whose access is specified by the corresponding
1255          * method
1256          * {@link VarHandle#addAndGet VarHandle.addAndGet}
1257          */
1258         ADD_AND_GET("addAndGet", AccessType.GET_AND_UPDATE),
1259         ;
1260 
1261         static final Map<String, AccessMode> methodNameToAccessMode;
1262         static {
1263             // Initial capacity of # values is sufficient to avoid resizes
1264             // for the smallest table size (32)
1265             methodNameToAccessMode = new HashMap<>(AccessMode.values().length);
1266             for (AccessMode am : AccessMode.values()) {
1267                 methodNameToAccessMode.put(am.methodName, am);
1268             }
1269         }
1270 
1271         final String methodName;
1272         final AccessType at;
1273 
1274         AccessMode(final String methodName, AccessType at) {
1275             this.methodName = methodName;
1276             this.at = at;
1277 
1278             // Assert method name is correctly derived from value name
1279             assert methodName.equals(toMethodName(name()));
1280             // Assert that return type is correct
1281             // Otherwise, when disabled avoid using reflection
1282             assert at.returnType == getReturnType(methodName);
1283         }
1284 
1285         /**
1286          * Returns the {@code VarHandle} signature-polymorphic method name
1287          * associated with this {@code AccessMode} value
1288          *
1289          * @return the signature-polymorphic method name
1290          * @see #valueFromMethodName
1291          */
1292         public String methodName() {
1293             return methodName;
1294         }
1295 
1296         /**
1297          * Returns the {@code AccessMode} value associated with the specified
1298          * {@code VarHandle} signature-polymorphic method name.
1299          *
1300          * @param methodName the signature-polymorphic method name
1301          * @return the {@code AccessMode} value
1302          * @throws IllegalArgumentException if there is no {@code AccessMode}
1303          *         value associated with method name (indicating the method
1304          *         name does not correspond to a {@code VarHandle}
1305          *         signature-polymorphic method name).
1306          * @see #methodName
1307          */
1308         public static AccessMode valueFromMethodName(String methodName) {
1309             AccessMode am = methodNameToAccessMode.get(methodName);
1310             if (am != null) return am;
1311             throw new IllegalArgumentException("No AccessMode value for method name " + methodName);
1312         }
1313 
1314         private static String toMethodName(String name) {
1315             StringBuilder s = new StringBuilder(name.toLowerCase());
1316             int i;
1317             while ((i = s.indexOf("_")) !=  -1) {
1318                 s.deleteCharAt(i);
1319                 s.setCharAt(i, Character.toUpperCase(s.charAt(i)));
1320             }
1321             return s.toString();
1322         }
1323 
1324         private static Class<?> getReturnType(String name) {
1325             try {
1326                 Method m = VarHandle.class.getMethod(name, Object[].class);
1327                 return m.getReturnType();
1328             }
1329             catch (Exception e) {
1330                 throw newInternalError(e);
1331             }
1332         }
1333 
1334         @ForceInline
1335         static MemberName getMemberName(int ordinal, VarForm vform) {
1336             return vform.memberName_table[ordinal];
1337         }
1338     }
1339 
1340     static final class AccessDescriptor {
1341         final MethodType symbolicMethodTypeErased;
1342         final MethodType symbolicMethodTypeInvoker;
1343         final Class<?> returnType;
1344         final int type;
1345         final int mode;
1346 
1347         public AccessDescriptor(MethodType symbolicMethodType, int type, int mode) {
1348             this.symbolicMethodTypeErased = symbolicMethodType.erase();
1349             this.symbolicMethodTypeInvoker = symbolicMethodType.insertParameterTypes(0, VarHandle.class);
1350             this.returnType = symbolicMethodType.returnType();
1351             this.type = type;
1352             this.mode = mode;
1353         }
1354     }
1355 
1356     /**
1357      * Returns the variable type of variables referenced by this VarHandle.
1358      *
1359      * @return the variable type of variables referenced by this VarHandle
1360      */
1361     public final Class<?> varType() {
1362         MethodType typeSet = accessModeType(AccessMode.SET);
1363         return typeSet.parameterType(typeSet.parameterCount() - 1);
1364     }
1365 
1366     /**
1367      * Returns the coordinate types for this VarHandle.
1368      *
1369      * @return the coordinate types for this VarHandle. The returned
1370      * list is unmodifiable
1371      */
1372     public final List<Class<?>> coordinateTypes() {
1373         MethodType typeGet = accessModeType(AccessMode.GET);
1374         return typeGet.parameterList();
1375     }
1376 
1377     /**
1378      * Obtains the canonical access mode type for this VarHandle and a given
1379      * access mode.
1380      *
1381      * <p>The access mode type's parameter types will consist of a prefix that
1382      * is the coordinate types of this VarHandle followed by further
1383      * types as defined by the access mode's method.
1384      * The access mode type's return type is defined by the return type of the
1385      * access mode's method.
1386      *
1387      * @param accessMode the access mode, corresponding to the
1388      * signature-polymorphic method of the same name
1389      * @return the access mode type for the given access mode
1390      */
1391     public final MethodType accessModeType(AccessMode accessMode) {
1392         TypesAndInvokers tis = getTypesAndInvokers();
1393         MethodType mt = tis.methodType_table[accessMode.at.ordinal()];
1394         if (mt == null) {
1395             mt = tis.methodType_table[accessMode.at.ordinal()] =
1396                     accessModeTypeUncached(accessMode);
1397         }
1398         return mt;
1399     }
1400     abstract MethodType accessModeTypeUncached(AccessMode accessMode);
1401 
1402     /**
1403      * Returns {@code true} if the given access mode is supported, otherwise
1404      * {@code false}.
1405      *
1406      * <p>The return of a {@code false} value for a given access mode indicates
1407      * that an {@code UnsupportedOperationException} is thrown on invocation
1408      * of the corresponding access mode's signature-polymorphic method.
1409      *
1410      * @param accessMode the access mode, corresponding to the
1411      * signature-polymorphic method of the same name
1412      * @return {@code true} if the given access mode is supported, otherwise
1413      * {@code false}.
1414      */
1415     public final boolean isAccessModeSupported(AccessMode accessMode) {
1416         return AccessMode.getMemberName(accessMode.ordinal(), vform) != null;
1417     }
1418 
1419     /**
1420      * Obtains a method handle bound to this VarHandle and the given access
1421      * mode.
1422      *
1423      * @apiNote This method, for a VarHandle {@code vh} and access mode
1424      * {@code {access-mode}}, returns a method handle that is equivalent to
1425      * method handle {@code bhm} in the following code (though it may be more
1426      * efficient):
1427      * <pre>{@code
1428      * MethodHandle mh = MethodHandles.varHandleExactInvoker(
1429      *                       vh.accessModeType(VarHandle.AccessMode.{access-mode}));
1430      *
1431      * MethodHandle bmh = mh.bindTo(vh);
1432      * }</pre>
1433      *
1434      * @param accessMode the access mode, corresponding to the
1435      * signature-polymorphic method of the same name
1436      * @return a method handle bound to this VarHandle and the given access mode
1437      */
1438     public final MethodHandle toMethodHandle(AccessMode accessMode) {
1439         MemberName mn = AccessMode.getMemberName(accessMode.ordinal(), vform);
1440         if (mn != null) {
1441             MethodHandle mh = getMethodHandle(accessMode.ordinal());
1442             return mh.bindTo(this);
1443         }
1444         else {
1445             // Ensure an UnsupportedOperationException is thrown
1446             return MethodHandles.varHandleInvoker(accessMode, accessModeType(accessMode)).
1447                     bindTo(this);
1448         }
1449     }
1450 
1451     @Stable
1452     TypesAndInvokers typesAndInvokers;
1453 
1454     static class TypesAndInvokers {
1455         final @Stable
1456         MethodType[] methodType_table =
1457                 new MethodType[VarHandle.AccessType.values().length];
1458 
1459         final @Stable
1460         MethodHandle[] methodHandle_table =
1461                 new MethodHandle[AccessMode.values().length];
1462     }
1463 
1464     @ForceInline
1465     private final TypesAndInvokers getTypesAndInvokers() {
1466         TypesAndInvokers tis = typesAndInvokers;
1467         if (tis == null) {
1468             tis = typesAndInvokers = new TypesAndInvokers();
1469         }
1470         return tis;
1471     }
1472 
1473     @ForceInline
1474     final MethodHandle getMethodHandle(int mode) {
1475         TypesAndInvokers tis = getTypesAndInvokers();
1476         MethodHandle mh = tis.methodHandle_table[mode];
1477         if (mh == null) {
1478             mh = tis.methodHandle_table[mode] = getMethodHandleUncached(tis, mode);
1479         }
1480         return mh;
1481     }
1482     private final MethodHandle getMethodHandleUncached(TypesAndInvokers tis, int mode) {
1483         MethodType mt = accessModeType(AccessMode.values()[mode]).
1484                 insertParameterTypes(0, VarHandle.class);
1485         MemberName mn = vform.getMemberName(mode);
1486         DirectMethodHandle dmh = DirectMethodHandle.make(mn);
1487         // Such a method handle must not be publically exposed directly
1488         // otherwise it can be cracked, it must be transformed or rebound
1489         // before exposure
1490         MethodHandle mh = dmh.copyWith(mt, dmh.form);
1491         assert mh.type().erase() == mn.getMethodType().erase();
1492         return mh;
1493     }
1494 
1495 
1496     /*non-public*/
1497     final void updateVarForm(VarForm newVForm) {
1498         if (vform == newVForm) return;
1499         UNSAFE.putObject(this, VFORM_OFFSET, newVForm);
1500         UNSAFE.fullFence();
1501     }
1502 
1503     static final BiFunction<String, List<Integer>, ArrayIndexOutOfBoundsException>
1504             AIOOBE_SUPPLIER = Objects.outOfBoundsExceptionFormatter(
1505             new Function<String, ArrayIndexOutOfBoundsException>() {
1506                 @Override
1507                 public ArrayIndexOutOfBoundsException apply(String s) {
1508                     return new ArrayIndexOutOfBoundsException(s);
1509                 }
1510             });
1511 
1512     private static final long VFORM_OFFSET;
1513 
1514     static {
1515         try {
1516             VFORM_OFFSET = UNSAFE.objectFieldOffset(VarHandle.class.getDeclaredField("vform"));
1517         }
1518         catch (ReflectiveOperationException e) {
1519             throw newInternalError(e);
1520         }
1521 
1522         // The VarHandleGuards must be initialized to ensure correct
1523         // compilation of the guard methods
1524         UNSAFE.ensureClassInitialized(VarHandleGuards.class);
1525     }
1526 
1527 
1528     // Fence methods
1529 
1530     /**
1531      * Ensures that loads and stores before the fence will not be reordered
1532      * with
1533      * loads and stores after the fence.
1534      *
1535      * @apiNote Ignoring the many semantic differences from C and C++, this
1536      * method has memory ordering effects compatible with
1537      * {@code atomic_thread_fence(memory_order_seq_cst)}
1538      */
1539     @ForceInline
1540     public static void fullFence() {
1541         UNSAFE.fullFence();
1542     }
1543 
1544     /**
1545      * Ensures that loads before the fence will not be reordered with loads and
1546      * stores after the fence.
1547      *
1548      * @apiNote Ignoring the many semantic differences from C and C++, this
1549      * method has memory ordering effects compatible with
1550      * {@code atomic_thread_fence(memory_order_acquire)}
1551      */
1552     @ForceInline
1553     public static void acquireFence() {
1554         UNSAFE.loadFence();
1555     }
1556 
1557     /**
1558      * Ensures that loads and stores before the fence will not be
1559      * reordered with stores after the fence.
1560      *
1561      * @apiNote Ignoring the many semantic differences from C and C++, this
1562      * method has memory ordering effects compatible with
1563      * {@code atomic_thread_fence(memory_order_release)}
1564      */
1565     @ForceInline
1566     public static void releaseFence() {
1567         UNSAFE.storeFence();
1568     }
1569 
1570     /**
1571      * Ensures that loads before the fence will not be reordered with
1572      * loads after the fence.
1573      */
1574     @ForceInline
1575     public static void loadLoadFence() {
1576         UNSAFE.loadLoadFence();
1577     }
1578 
1579     /**
1580      * Ensures that stores before the fence will not be reordered with
1581      * stores after the fence.
1582      */
1583     @ForceInline
1584     public static void storeStoreFence() {
1585         UNSAFE.storeStoreFence();
1586     }
1587 }