Skip to content

JDK-8289775: Update java.lang.invoke.MethodHandle[s] to use snippets #9385

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

JDK-8289775: Update java.lang.invoke.MethodHandle[s] to use snippets #9385

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 22 additions & 22 deletions src/java.base/share/classes/java/lang/invoke/MethodHandle.java
View file
Open in desktop
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;
Copy link
Member

Choose a reason for hiding this comment

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

These lines can now be properly indented, and they should be.

Copy link
Member Author

Choose a reason for hiding this comment

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

That isn't an unreasonable suggestion. However, I wanted to present this change in an easy-to-review fashion so limited the diffs to the bracketing tags.

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
Loading