> On 28 Apr 2017, at 14:55, Alex Buckley <alex.buck...@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
