Skip to content

Commit

Permalink
8289775: Update java.lang.invoke.MethodHandle[s] to use snippets
Browse files Browse the repository at this point in the history
Reviewed-by: jrose
  • Loading branch information
jddarcy committed Jul 6, 2022
1 parent 2a6ec88 commit a40c17b
Show file tree
Hide file tree
Showing 2 changed files with 122 additions and 123 deletions.
44 changes: 22 additions & 22 deletions src/java.base/share/classes/java/lang/invoke/MethodHandle.java
Original file line number Diff line number Diff line change
Expand Up @@ -268,7 +268,7 @@
*
* <h2>Usage examples</h2>
* Here are some examples of usage:
* <blockquote><pre>{@code
* {@snippet lang="java" :
Object x, y; String s; int i;
MethodType mt; MethodHandle mh;
MethodHandles.Lookup lookup = MethodHandles.lookup();
Expand Down Expand Up @@ -304,7 +304,7 @@
mh = lookup.findVirtual(java.io.PrintStream.class, "println", mt);
mh.invokeExact(System.out, "Hello, world.");
// invokeExact(Ljava/io/PrintStream;Ljava/lang/String;)V
* }</pre></blockquote>
* }
* Each of the above calls to {@code invokeExact} or plain {@code invoke}
* generates a single invokevirtual instruction with
* the symbolic type descriptor indicated in the following comment.
Expand Down Expand Up @@ -695,7 +695,7 @@ public MethodType type() {
* It can therefore be used as a bridge between native or reflective code and method handles.
* @apiNote
* This call is approximately equivalent to the following code:
* <blockquote><pre>{@code
* {@snippet lang="java" :
* // for jumbo argument lists, adapt varargs explicitly:
* int N = (arguments == null? 0: arguments.length);
* int M = this.type.parameterCount();
Expand All @@ -718,7 +718,7 @@ public MethodType type() {
* // Handle fixed arity and non-jumbo variable arity invocation.
* MethodHandle invoker = MethodHandles.spreadInvoker(this.type(), 0);
* Object result = invoker.invokeExact(this, arguments);
* }</pre></blockquote>
* }
*
* @param arguments the arguments to pass to the target
* @return the result returned by the target
Expand All @@ -740,9 +740,9 @@ public Object invokeWithArguments(Object... arguments) throws Throwable {
* of the argument list.
* <p>
* This method is also equivalent to the following code:
* <blockquote><pre>{@code
* {@snippet lang="java" :
* invokeWithArguments(arguments.toArray())
* }</pre></blockquote>
* }
* <p>
* Jumbo-sized lists are acceptable if this method handle has variable arity.
* See {@link #invokeWithArguments(Object[])} for details.
Expand Down Expand Up @@ -1008,7 +1008,7 @@ private static boolean isBuiltinLoader(ClassLoader loader) {
* if the array does not have the correct number of elements.
* <p>
* Here are some simple examples of array-spreading method handles:
* <blockquote><pre>{@code
* {@snippet lang="java" :
MethodHandle equals = publicLookup()
.findVirtual(String.class, "equals", methodType(boolean.class, Object.class));
assert( (boolean) equals.invokeExact("me", (Object)"me"));
Expand Down Expand Up @@ -1050,7 +1050,7 @@ private static boolean isBuiltinLoader(ClassLoader loader) {
assertEquals("[A, B, C]", (String) caString3.invokeExact('A', 'B', 'C'));
MethodHandle caToString2 = caString3.asSpreader(char[].class, 2);
assertEquals("[A, B, C]", (String) caToString2.invokeExact('A', "BC".toCharArray()));
* }</pre></blockquote>
* }
* @param arrayType usually {@code Object[]}, the type of the array argument from which to extract the spread arguments
* @param arrayLength the number of arguments to spread from an incoming array argument
* @return a new method handle which spreads its final array argument,
Expand Down Expand Up @@ -1080,15 +1080,15 @@ public MethodHandle asSpreader(Class<?> arrayType, int arrayLength) {
* argument to indicate at which position in the parameter list the spreading should take place.
*
* @apiNote Example:
* <blockquote><pre>{@code
* {@snippet lang="java" :
MethodHandle compare = LOOKUP.findStatic(Objects.class, "compare", methodType(int.class, Object.class, Object.class, Comparator.class));
MethodHandle compare2FromArray = compare.asSpreader(0, Object[].class, 2);
Object[] ints = new Object[]{3, 9, 7, 7};
Comparator<Integer> cmp = (a, b) -> a - b;
assertTrue((int) compare2FromArray.invoke(Arrays.copyOfRange(ints, 0, 2), cmp) < 0);
assertTrue((int) compare2FromArray.invoke(Arrays.copyOfRange(ints, 1, 3), cmp) > 0);
assertTrue((int) compare2FromArray.invoke(Arrays.copyOfRange(ints, 2, 4), cmp) == 0);
* }</pre></blockquote>
* }
* @param spreadArgPos the position (zero-based index) in the argument list at which spreading should start.
* @param arrayType usually {@code Object[]}, the type of the array argument from which to extract the spread arguments
* @param arrayLength the number of arguments to spread from an incoming array argument
Expand Down Expand Up @@ -1179,14 +1179,14 @@ private void spreadArrayChecks(Class<?> arrayType, int arrayLength) {
* .withVarargs(mh.isVarargsCollector())}
* <p>
* This call is approximately equivalent to the following code:
* <blockquote><pre>{@code
* {@snippet lang="java" :
* if (makeVarargs == isVarargsCollector())
* return this;
* else if (makeVarargs)
* return asVarargsCollector(type().lastParameterType());
* else
* return asFixedArity();
* }</pre></blockquote>
* }
* @param makeVarargs true if the return method handle should have variable arity behavior
* @return a method handle of the same type, with possibly adjusted variable arity behavior
* @throws IllegalArgumentException if {@code makeVarargs} is true and
Expand Down Expand Up @@ -1236,7 +1236,7 @@ public MethodHandle withVarargs(boolean makeVarargs) {
* or {@link #withVarargs withVarargs} instead.
* <p>
* Here are some examples of array-collecting method handles:
* <blockquote><pre>{@code
* {@snippet lang="java" :
MethodHandle deepToString = publicLookup()
.findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));
assertEquals("[won]", (String) deepToString.invokeExact(new Object[]{"won"}));
Expand All @@ -1262,7 +1262,7 @@ public MethodHandle withVarargs(boolean makeVarargs) {
.findStatic(Arrays.class, "toString", methodType(String.class, long[].class))
.asCollector(long[].class, 1);
assertEquals("[123]", (String) longsToString.invokeExact((long)123));
* }</pre></blockquote>
* }
* <p>
* <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
* variable-arity method handle}, even if the original target method handle was.
Expand Down Expand Up @@ -1296,7 +1296,7 @@ public MethodHandle asCollector(Class<?> arrayType, int arrayLength) {
* index is zero-based.
*
* @apiNote Examples:
* <blockquote><pre>{@code
* {@snippet lang="java" :
StringWriter swr = new StringWriter();
MethodHandle swWrite = LOOKUP.findVirtual(StringWriter.class, "write", methodType(void.class, char[].class, int.class, int.class)).bindTo(swr);
MethodHandle swWrite4 = swWrite.asCollector(0, char[].class, 4);
Expand All @@ -1306,7 +1306,7 @@ public MethodHandle asCollector(Class<?> arrayType, int arrayLength) {
assertEquals("BCPQRS", swr.toString());
swWrite4.invoke('W', 'X', 'Y', 'Z', 3, 1);
assertEquals("BCPQRSZ", swr.toString());
* }</pre></blockquote>
* }
* <p>
* <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
* variable-arity method handle}, even if the original target method handle was.
Expand Down Expand Up @@ -1459,7 +1459,7 @@ boolean asCollectorChecks(Class<?> arrayType, int pos, int arrayLength) {
* It may (or may not) return the original variable arity method handle.
* <p>
* Here is an example, of a list-making variable arity method handle:
* <blockquote><pre>{@code
* {@snippet lang="java" :
MethodHandle deepToString = publicLookup()
.findStatic(Arrays.class, "deepToString", methodType(String.class, Object[].class));
MethodHandle ts1 = deepToString.asVarargsCollector(Object[].class);
Expand All @@ -1481,7 +1481,7 @@ boolean asCollectorChecks(Class<?> arrayType, int pos, int arrayLength) {
List ls = (List) asList.invoke((Object)argv);
assertEquals(1, ls.size());
assertEquals("[three, thee, tee]", Arrays.toString((Object[])ls.get(0)));
* }</pre></blockquote>
* }
* <p style="font-size:smaller;">
* <em>Discussion:</em>
* These rules are designed as a dynamically-typed variation
Expand Down Expand Up @@ -1553,7 +1553,7 @@ public boolean isVarargsCollector() {
* previous argument to {@code asVarargsCollector}.
* <p>
* Here is an example, of a list-making variable arity method handle:
* <blockquote><pre>{@code
* {@snippet lang="java" :
MethodHandle asListVar = publicLookup()
.findStatic(Arrays.class, "asList", methodType(List.class, Object[].class))
.asVarargsCollector(Object[].class);
Expand All @@ -1572,7 +1572,7 @@ public boolean isVarargsCollector() {
assertEquals("[three, thee, tee]", asListFix.invoke(argv).toString());
assertEquals(1, ((List) asListVar.invoke((Object)argv)).size());
assertEquals("[three, thee, tee]", asListFix.invoke((Object)argv).toString());
* }</pre></blockquote>
* }
*
* @return a new method handle which accepts only a fixed number of arguments
* @see #asVarargsCollector
Expand Down Expand Up @@ -1668,9 +1668,9 @@ public Optional<MethodHandleDesc> describeConstable() {
* starting with the string {@code "MethodHandle"} and
* ending with the string representation of the method handle's type.
* In other words, this method returns a string equal to the value of:
* <blockquote><pre>{@code
* {@snippet lang="java" :
* "MethodHandle" + type().toString()
* }</pre></blockquote>
* }
* <p>
* (<em>Note:</em> Future releases of this API may add further information
* to the string representation.
Expand Down

1 comment on commit a40c17b

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.