jdk-sandbox: comparison jdk/src/java.base/share/classes/java/lang/invoke/VarHandle.java

equal deleted inserted replaced

-:35a2231828a7
+:52d3d8517efc
 * <p>Factory methods that produce or {@link java.lang.invoke.MethodHandles.Lookup
 * lookup} VarHandle instances document the set of access modes that are
 * supported, which may also include documenting restrictions based on the
 * variable type and whether a variable is read-only.  If an access mode is not
 * supported then the corresponding signature-polymorphic method will on
-* invocation throw an {@code UnsupportedOperationException}.
+* invocation throw an {@code UnsupportedOperationException}.  Factory methods
+* should document any additional undeclared exceptions that may be thrown by
+* access mode methods.
 * The {@link #get get} access mode is supported for all
 * VarHandle instances and the corresponding method never throws
 * {@code UnsupportedOperationException}.
 * If a VarHandle references a read-only variable (for example a {@code final}
 * field) then write, atomic update and numeric atomic update access modes are
 * {@code get} and {@code set}, provide atomic access for
 * reference types and all primitive types.
 * Unless stated otherwise in the documentation of a factory method, the access
 * modes {@code get} and {@code set} (if supported) provide atomic access for
 * reference types and all primitives types, with the exception of {@code long}
-* and {@code double} on 32-bit platforms
+* and {@code double} on 32-bit platforms.
 *
 * <p>Access modes will override any memory ordering effects specified at
 * the declaration site of a variable.  For example, a VarHandle accessing a
 * a field using the {@code get} access mode will access the field as
 * specified <em>by its access mode</em> even if that field is declared
 * @return the signature-polymorphic result that is the value of the
 * variable
 * , statically represented using {@code Object}.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 */
 public final native
 @MethodHandle.PolymorphicSignature
 @HotSpotIntrinsicCandidate
 Object get(Object... args);
 * , statically represented using varargs.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 */
 public final native
 @MethodHandle.PolymorphicSignature
 @HotSpotIntrinsicCandidate
 void set(Object... args);
 * , statically represented using {@code Object}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 */
 public final native
 @MethodHandle.PolymorphicSignature
 @HotSpotIntrinsicCandidate
 Object getVolatile(Object... args);
 *
 * <p>The symbolic type descriptor at the call site of {@code setVolatile}
 * must match the access mode type that is the result of calling
 * {@code accessModeType(VarHandle.AccessMode.setVolatile)} on this VarHandle.
 *
+* @apiNote
+* Ignoring the many semantic differences from C and C++, this method has
+* memory ordering effects compatible with {@code memory_order_seq_cst}.
+*
 * @param args the signature-polymorphic parameter list of the form
 * {@code (CT, T newValue)}
 * , statically represented using varargs.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
-* @apiNote Ignoring the many semantic differences from C and C++, this
+* @throws ClassCastException if the access mode type is compatible with the
-* method has memory ordering effects compatible with
+* caller's symbolic type descriptor, but a reference cast fails.
-* {@code memory_order_seq_cst}.
 */
 public final native
 @MethodHandle.PolymorphicSignature
 @HotSpotIntrinsicCandidate
 void setVolatile(Object... args);
 * , statically represented using {@code Object}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 */
 public final native
 @MethodHandle.PolymorphicSignature
 @HotSpotIntrinsicCandidate
 Object getOpaque(Object... args);
 * , statically represented using varargs.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 */
 public final native
 @MethodHandle.PolymorphicSignature
 @HotSpotIntrinsicCandidate
 void setOpaque(Object... args);
 * <p>The method signature is of the form {@code (CT)T}.
 *
 * <p>The symbolic type descriptor at the call site of {@code getAcquire}
 * must match the access mode type that is the result of calling
 * {@code accessModeType(VarHandle.AccessMode.getAcquire)} on this VarHandle.
+*
+* @apiNote
+* Ignoring the many semantic differences from C and C++, this method has
+* memory ordering effects compatible with {@code memory_order_acquire}
+* ordering.
 *
 * @param args the signature-polymorphic parameter list of the form
 * {@code (CT)}
 * , statically represented using varargs.
 * @return the signature-polymorphic result that is the value of the
 * , statically represented using {@code Object}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
-* @apiNote Ignoring the many semantic differences from C and C++, this
+* @throws ClassCastException if the access mode type is compatible with the
-* method has memory ordering effects compatible with
+* caller's symbolic type descriptor, but a reference cast fails.
-* {@code memory_order_acquire} ordering.
 */
 public final native
 @MethodHandle.PolymorphicSignature
 @HotSpotIntrinsicCandidate
 Object getAcquire(Object... args);
 *
 * <p>The symbolic type descriptor at the call site of {@code setRelease}
 * must match the access mode type that is the result of calling
 * {@code accessModeType(VarHandle.AccessMode.setRelease)} on this VarHandle.
 *
+* @apiNote
+* Ignoring the many semantic differences from C and C++, this method has
+* memory ordering effects compatible with {@code memory_order_release}
+* ordering.
+*
 * @param args the signature-polymorphic parameter list of the form
 * {@code (CT, T newValue)}
 * , statically represented using varargs.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
-* @apiNote Ignoring the many semantic differences from C and C++, this
+* @throws ClassCastException if the access mode type is compatible with the
-* method has memory ordering effects compatible with
+* caller's symbolic type descriptor, but a reference cast fails.
-* {@code memory_order_release} ordering.
 */
 public final native
 @MethodHandle.PolymorphicSignature
 @HotSpotIntrinsicCandidate
 void setRelease(Object... args);
 * witness value was not the same as the {@code expectedValue}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #setVolatile(Object...)
 * @see #getVolatile(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature
 * , statically represented using {@code Object}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #setVolatile(Object...)
 * @see #getVolatile(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature
 * , statically represented using {@code Object}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #set(Object...)
 * @see #getAcquire(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature
 * , statically represented using {@code Object}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #setRelease(Object...)
 * @see #get(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature
 * operation spuriously failed.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #set(Object...)
 * @see #get(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature
 * operation spuriously failed.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #set(Object...)
 * @see #getAcquire(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature
 * operation spuriously failed.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #setRelease(Object...)
 * @see #get(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature
 * , statically represented using {@code Object}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #setVolatile(Object...)
 * @see #getVolatile(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature
 * , statically represented using {@code Object}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #setVolatile(Object...)
 * @see #getVolatile(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature
 * , statically represented using {@code Object}.
 * @throws UnsupportedOperationException if the access mode is unsupported
 * for this VarHandle.
 * @throws WrongMethodTypeException if the access mode type is not
 * compatible with the caller's symbolic type descriptor.
+* @throws ClassCastException if the access mode type is compatible with the
+* caller's symbolic type descriptor, but a reference cast fails.
 * @see #setVolatile(Object...)
 * @see #getVolatile(Object...)
 */
 public final native
 @MethodHandle.PolymorphicSignature

changeset 37344	52d3d8517efc
parent 37343	35a2231828a7
child 37345	9cb6e1141bdb