[JDK9] RFR 8167229: Improve VarHandle documentation

Fri Apr 28 22:39:43 UTC 2017

> On 28 Apr 2017, at 14:55, Alex Buckley <alex.buckley at Oracle.COM> wrote:
> 
> On 4/26/2017 4:06 PM, Paul Sandoz wrote:
>> Please review some documentation changes to VarHandle:
>> 
>> http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8167229-varhandle-docs/webrev/index.html
> 
> I notice that "shape" is still mentioned throughout the MethodHandles.Lookup class.
> 

Are you looking at the old version? I removed ‘em all from the new version.


> 59  * {@code CT1, CT2, ..., CTn}, the types of <em>coordinate expressions</em> that
> 60  * uniquely locate a variable referenced by this VarHandle.
> 
> I'm unsure of "uniquely locate". Distinct coordinate expressions can refer to the same object, due to aliasing. And there is nothing said later about one VarHandle being the exclusive systemwide locator of a variable. Do you mean "that _jointly_ locate a variable …”

Ok, good point, it should be unique within the confines of a VarHandle instance, but could be aliased by another VarHandle instance or something else.


> ?
> 

> 73  * instance, the initial arguments to the invocation are coordinate expressions
> 74  * that indicate precisely which variable is to be accessed.
> 
> "that indicate _in precisely which object_ the variable is to be accessed.”

Ok.


> ?
> 

> BTW Since "array elements" are mentioned in the opening paragraph, and since here is an example involving String[] as a coordinate type later, it would be nice to say how a VarHandle pointing to an array element can be created.
> 

Ok.


> 209  * <h1>Compilation of an access mode's method</h1>
> 
> First, the term "access mode's method" appears only here and in accessModeType, but I think you mean "mode" not "mode's”.
> 

Yes, i updated all relevant places.


> Second, this section isn't about compilation of the method. Access mode methods are not native and there is nothing to suggest that a suitably skilled platform developer can't write one in Java and compile it -- yet this section will not tell them how to compile it. (I appreciate the style comes from j.l.i.MethodHandle, and it would be better to avoid speaking of "Method handle compilation" there.) I recommend "Invoking access mode methods from source code" and "Invoking access mode methods from bytecode". Or "Compiling invocation of access mode methods" and "Performing invocation of access mode methods”.

I opted for the later.

Below is a diff on the webrev.

Thanks,
Paul.

diff -r 64fdd70fe45c src/java.base/share/classes/java/lang/invoke/VarHandle.java

--- a/src/java.base/share/classes/java/lang/invoke/VarHandle.java	Fri Apr 28 15:03:01 2017 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/VarHandle.java	Fri Apr 28 15:36:04 2017 -0700
@@ -57,7 +57,7 @@
  * by this VarHandle; and
  * <li>a list of {@link #coordinateTypes coordinate types}
  * {@code CT1, CT2, ..., CTn}, the types of <em>coordinate expressions</em> that
- * uniquely locate a variable referenced by this VarHandle.
+ * jointly locate a variable referenced by this VarHandle.
  * </ul>
  * Variable and coordinate types may be primitive or reference, and are
  * represented by {@code Class} objects.  The list of coordinate types may be
@@ -71,11 +71,11 @@
  * <a href="MethodHandle.html#sigpoly">signature polymorphic</a> method named
  * for the access mode.  When an access mode method is invoked on a VarHandle
  * instance, the initial arguments to the invocation are coordinate expressions
- * that indicate precisely which variable is to be accessed.  Trailing arguments
- * to the invocation represent values of importance to the access mode.  For
- * example, the various compare-and-set or compare-and-exchange access modes
- * require two trailing arguments for the variable's expected value and new
- * value.
+ * that indicate in precisely which object the variable is to be accessed.
+ * Trailing arguments to the invocation represent values of importance to the
+ * access mode.  For example, the various compare-and-set or compare-and-exchange
+ * access modes require two trailing arguments for the variable's expected value
+ * and new value.
  *
  * <p>The arity and types of arguments to the invocation of an access mode
  * method are not checked statically.  Instead, each access mode method
@@ -101,6 +101,14 @@
  * is {@code String}.  The access mode type for {@code compareAndSet} on this
  * VarHandle instance would be
  * {@code (String[] c1, int c2, String expectedValue, String newValue)boolean}.
+ * Such a VarHandle instance may produced by the
+ * {@link MethodHandles#arrayElementVarHandle(Class) array factory method} and
+ * access array elements as follows:
+ * <pre> {@code
+ * String[] sa = ...
+ * VarHandle avh = MethodHandles.arrayElementVarHandle(String[].class);
+ * avh.compareAndSet(sa, 10, "expected", "new");
+ * }</pre>
  *
  * <p>Access modes are grouped into the following categories:
  * <ul>
@@ -206,7 +214,7 @@
  * precise phrasing of the specification of access mode methods and memory fence
  * methods may accompany future updates of the Java Language Specification.
  *
- * <h1>Compilation of an access mode's method</h1>
+ * <h1>Compiling invocation of access mode methods</h1>
  * A Java method call expression naming an access mode method can invoke a
  * VarHandle from Java source code.  From the viewpoint of source code, these
  * methods can take any arguments and their polymorphic result (if expressed)
@@ -238,7 +246,7 @@
  * except the null reference.
  *
  *
- * <h1><a name="invoke">Invocation of an access mode's method</a></h1>
+ * <h1><a name="invoke">Performing invocation of access mode methods</a></h1>
  * The first time an {@code invokevirtual} instruction is executed it is linked
  * by symbolically resolving the names in the instruction and verifying that
  * the method call is statically legal.  This also holds for calls to access mode
@@ -255,11 +263,11 @@
  * invoking is not present on the individual VarHandle being invoked.
  *
  * <p>
- * Invocation of an access mode's signature-polymorphic method behaves as if an
- * invocation of {@link MethodHandle#invoke}, where the receiving method handle
- * accepts the VarHandle instance as the leading argument.  More specifically,
- * the following, where {@code {access-mode}} corresponds to the access mode
- * method name:
+ * Invocation of an access mode method behaves as if an invocation of
+ * {@link MethodHandle#invoke}, where the receiving method handle accepts the
+ * VarHandle instance as the leading argument.  More specifically, the
+ * following, where {@code {access-mode}} corresponds to the access mode method
+ * name:
  * <pre> {@code
  * VarHandle vh = ..
  * R r = (R) vh.{access-mode}(p1, p2, ..., pN);
@@ -1856,14 +1864,13 @@
     }

     /**
-     * Obtains the canonical access mode type for this VarHandle and a given
-     * access mode.
+     * Obtains the access mode type for this VarHandle and a given access mode.
      *
      * <p>The access mode type's parameter types will consist of a prefix that
      * is the coordinate types of this VarHandle followed by further
-     * types as defined by the access mode's method.
+     * types as defined by the access mode method.
      * The access mode type's return type is defined by the return type of the
-     * access mode's method.
+     * access mode method.
      *
      * @param accessMode the access mode, corresponding to the
      * signature-polymorphic method of the same name
@@ -1886,7 +1893,7 @@
      *
      * <p>The return of a {@code false} value for a given access mode indicates
      * that an {@code UnsupportedOperationException} is thrown on invocation
-     * of the corresponding access mode's signature-polymorphic method.
+     * of the corresponding access mode method.
      *
      * @param accessMode the access mode, corresponding to the
      * signature-polymorphic method of the same name


