--- old/src/java.base/share/classes/java/lang/invoke/MethodHandle.java 2015-11-19 22:13:59.000000000 +0100
+++ new/src/java.base/share/classes/java/lang/invoke/MethodHandle.java 2015-11-19 22:13:59.000000000 +0100
@@ -872,13 +872,54 @@
* @see #asCollector
*/
public MethodHandle asSpreader(Class> arrayType, int arrayLength) {
- MethodType postSpreadType = asSpreaderChecks(arrayType, arrayLength);
- int arity = type().parameterCount();
- int spreadArgPos = arity - arrayLength;
+ return asSpreader(type().parameterCount() - arrayLength, arrayType, arrayLength);
+ }
+
+ /**
+ * Makes an array-spreading method handle, which accepts an array argument at a given position and spreads
+ * its elements as positional arguments in place of the array. The new method handle adapts, as its target,
+ * the current method handle. The type of the adapter will be the same as the type of the target, except that the
+ * {@code arrayLength} parameters of the target's type, starting at the zero-based position {@code spreadArgPos},
+ * are replaced by a single array parameter of type {@code arrayType}.
+ *
+ * This method behaves very much like {@link #asSpreader(Class, int)}, but accepts an additional {@code spreadArgPos}
+ * argument to indicate at which position in the parameter list the spreading should take place.
+ *
+ * @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
+ * @return a new method handle which spreads an array argument at a given position,
+ * before calling the original method handle
+ * @throws NullPointerException if {@code arrayType} is a null reference
+ * @throws IllegalArgumentException if {@code arrayType} is not an array type,
+ * or if target does not have at least
+ * {@code arrayLength} parameter types,
+ * or if {@code arrayLength} is negative,
+ * or if {@code spreadArgPos} has an illegal value (negative, or together with arrayLength exceeding the
+ * number of arguments),
+ * or if the resulting method handle's type would have
+ * too many parameters
+ * @throws WrongMethodTypeException if the implied {@code asType} call fails
+ *
+ * @see #asSpreader(Class, int)
+ * @since 9
+ */
+ public MethodHandle asSpreader(int spreadArgPos, Class> arrayType, int arrayLength) {
+ MethodType postSpreadType = asSpreaderChecks(arrayType, spreadArgPos, arrayLength);
MethodHandle afterSpread = this.asType(postSpreadType);
BoundMethodHandle mh = afterSpread.rebind();
LambdaForm lform = mh.editor().spreadArgumentsForm(1 + spreadArgPos, arrayType, arrayLength);
- MethodType preSpreadType = postSpreadType.replaceParameterTypes(spreadArgPos, arity, arrayType);
+ MethodType preSpreadType = postSpreadType.replaceParameterTypes(spreadArgPos, spreadArgPos + arrayLength, arrayType);
return mh.copyWith(preSpreadType, lform);
}
@@ -886,15 +927,18 @@
* See if {@code asSpreader} can be validly called with the given arguments.
* Return the type of the method handle call after spreading but before conversions.
*/
- private MethodType asSpreaderChecks(Class> arrayType, int arrayLength) {
+ private MethodType asSpreaderChecks(Class> arrayType, int pos, int arrayLength) {
spreadArrayChecks(arrayType, arrayLength);
int nargs = type().parameterCount();
if (nargs < arrayLength || arrayLength < 0)
throw newIllegalArgumentException("bad spread array length");
+ if (pos < 0 || pos + arrayLength > nargs) {
+ throw newIllegalArgumentException("bad spread position");
+ }
Class> arrayElement = arrayType.getComponentType();
MethodType mtype = type();
boolean match = true, fail = false;
- for (int i = nargs - arrayLength; i < nargs; i++) {
+ for (int i = pos; i < arrayLength; i++) {
Class> ptype = mtype.parameterType(i);
if (ptype != arrayElement) {
match = false;
@@ -905,7 +949,7 @@
}
}
if (match) return mtype;
- MethodType needType = mtype.asSpreaderType(arrayType, arrayLength);
+ MethodType needType = mtype.asSpreaderType(arrayType, pos, arrayLength);
if (!fail) return needType;
// elicit an error:
this.asType(needType);
@@ -998,10 +1042,53 @@
* @see #asVarargsCollector
*/
public MethodHandle asCollector(Class> arrayType, int arrayLength) {
- asCollectorChecks(arrayType, arrayLength);
- int collectArgPos = type().parameterCount() - 1;
+ return asCollector(type().parameterCount() - 1, arrayType, arrayLength);
+ }
+
+ /**
+ * Makes an array-collecting method handle, which accepts a given number of positional arguments starting
+ * at a given position, and collects them into an array argument. The new method handle adapts, as its
+ * target, the current method handle. The type of the adapter will be the same as the type of the target,
+ * except that the parameter at the position indicated by {@code collectArgPos} (usually of type {@code arrayType})
+ * is replaced by {@code arrayLength} parameters whose type is element type of {@code arrayType}.
+ *
+ * This method behaves very much like {@link #asCollector(Class, int)}, but differs in that its {@code
+ * collectArgPos} argument indicates at which position in the parameter list arguments should be collected. This
+ * index is zero-based.
+ *
+ * @param collectArgPos the zero-based position in the parameter list at which to start collecting.
+ * @param arrayType often {@code Object[]}, the type of the array argument which will collect the arguments
+ * @param arrayLength the number of arguments to collect into a new array argument
+ * @return a new method handle which collects some arguments
+ * into an array, before calling the original method handle
+ * @throws NullPointerException if {@code arrayType} is a null reference
+ * @throws IllegalArgumentException if {@code arrayType} is not an array type
+ * or {@code arrayType} is not assignable to this method handle's array parameter type,
+ * or {@code arrayLength} is not a legal array size,
+ * or {@code collectArgPos} has an illegal value (negative, or greater than the number of arguments),
+ * or the resulting method handle's type would have
+ * too many parameters
+ * @throws WrongMethodTypeException if the implied {@code asType} call fails
+ *
+ * @see #asCollector(Class, int)
+ * @since 9
+ */
+ public MethodHandle asCollector(int collectArgPos, Class> arrayType, int arrayLength) {
+ asCollectorChecks(arrayType, collectArgPos, arrayLength);
BoundMethodHandle mh = rebind();
- MethodType resultType = type().asCollectorType(arrayType, arrayLength);
+ MethodType resultType = type().asCollectorType(arrayType, collectArgPos, arrayLength);
MethodHandle newArray = MethodHandleImpl.varargsArray(arrayType, arrayLength);
LambdaForm lform = mh.editor().collectArgumentArrayForm(1 + collectArgPos, newArray);
if (lform != null) {
@@ -1015,15 +1102,18 @@
* See if {@code asCollector} can be validly called with the given arguments.
* Return false if the last parameter is not an exact match to arrayType.
*/
- /*non-public*/ boolean asCollectorChecks(Class> arrayType, int arrayLength) {
+ /*non-public*/ boolean asCollectorChecks(Class> arrayType, int pos, int arrayLength) {
spreadArrayChecks(arrayType, arrayLength);
int nargs = type().parameterCount();
+ if (pos < 0 || pos >= nargs) {
+ throw newIllegalArgumentException("bad collect position");
+ }
if (nargs != 0) {
- Class> lastParam = type().parameterType(nargs-1);
- if (lastParam == arrayType) return true;
- if (lastParam.isAssignableFrom(arrayType)) return false;
+ Class> param = type().parameterType(pos);
+ if (param == arrayType) return true;
+ if (param.isAssignableFrom(arrayType)) return false;
}
- throw newIllegalArgumentException("array type not assignable to trailing argument", this, arrayType);
+ throw newIllegalArgumentException("array type not assignable to argument", this, arrayType);
}
/**
@@ -1178,7 +1268,7 @@
*/
public MethodHandle asVarargsCollector(Class> arrayType) {
Objects.requireNonNull(arrayType);
- boolean lastMatch = asCollectorChecks(arrayType, 0);
+ boolean lastMatch = asCollectorChecks(arrayType, type().parameterCount() - 1, 0);
if (isVarargsCollector() && lastMatch)
return this;
return MethodHandleImpl.makeVarargsCollector(this, arrayType);
@@ -1341,7 +1431,6 @@
// cannot be cracked into MethodHandleInfo.
assert viewAsTypeChecks(newType, strict);
BoundMethodHandle mh = rebind();
- assert(!((MethodHandle)mh instanceof DirectMethodHandle));
return mh.copyWith(newType, mh.form);
}
--- old/src/java.base/share/classes/java/lang/invoke/MethodHandleImpl.java 2015-11-19 22:14:01.000000000 +0100
+++ new/src/java.base/share/classes/java/lang/invoke/MethodHandleImpl.java 2015-11-19 22:14:00.000000000 +0100
@@ -27,16 +27,17 @@
import java.security.AccessController;
import java.security.PrivilegedAction;
-import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
import java.util.function.Function;
+import java.util.stream.Collectors;
import sun.invoke.empty.Empty;
import sun.invoke.util.ValueConversions;
import sun.invoke.util.VerifyType;
import sun.invoke.util.Wrapper;
-import jdk.internal.HotSpotIntrinsicCandidate;
import sun.reflect.CallerSensitive;
import sun.reflect.Reflection;
import static java.lang.invoke.LambdaForm.*;
@@ -1297,7 +1298,7 @@
@Override
public MethodHandle asCollector(Class> arrayType, int arrayLength) {
if (intrinsicName == Intrinsic.IDENTITY) {
- MethodType resultType = type().asCollectorType(arrayType, arrayLength);
+ MethodType resultType = type().asCollectorType(arrayType, type().parameterCount() - 1, arrayLength);
MethodHandle newArray = MethodHandleImpl.varargsArray(arrayType, arrayLength);
return newArray.asType(resultType);
}
@@ -1619,17 +1620,251 @@
}
}
+ /**
+ * Assembles a loop method handle from the given handles and type information. This works by binding and configuring
+ * the {@linkplain #looper(MethodHandle[], MethodHandle[], MethodHandle[], MethodHandle[], int, int, Object[]) "most
+ * generic loop"}.
+ *
+ * @param tloop the return type of the loop.
+ * @param targs types of the arguments to be passed to the loop.
+ * @param tvars types of loop-local variables.
+ * @param init sanitized array of initializers for loop-local variables.
+ * @param step sanitited array of loop bodies.
+ * @param pred sanitized array of predicates.
+ * @param fini sanitized array of loop finalizers.
+ *
+ * @return a handle that, when invoked, will execute the loop.
+ */
+ static MethodHandle makeLoop(Class> tloop, List> targs, List> tvars, List init,
+ List step, List pred, List fini) {
+ MethodHandle[] ainit = toArrayArgs(init);
+ MethodHandle[] astep = toArrayArgs(step);
+ MethodHandle[] apred = toArrayArgs(pred);
+ MethodHandle[] afini = toArrayArgs(fini);
+
+ MethodHandle l = getConstantHandle(MH_looper);
+
+ // Bind the statically known arguments.
+ l = MethodHandles.insertArguments(l, 0, ainit, astep, apred, afini, tvars.size(), targs.size());
+
+ // Turn the args array into an argument list.
+ l = l.asCollector(Object[].class, targs.size());
+
+ // Finally, make loop type.
+ MethodType loopType = MethodType.methodType(tloop, targs);
+ l = l.asType(loopType);
+
+ return l;
+ }
+
+ /**
+ * Converts all handles in the {@code hs} array to handles that accept an array of arguments.
+ *
+ * @param hs method handles to be converted.
+ *
+ * @return the {@code hs} array, with all method handles therein converted.
+ */
+ static MethodHandle[] toArrayArgs(List hs) {
+ return hs.stream().map(h -> h.asSpreader(Object[].class, h.type().parameterCount())).toArray(MethodHandle[]::new);
+ }
+
+ /**
+ * This method embodies the most generic loop for use by {@link MethodHandles#loop(MethodHandle[][])}. A handle on
+ * it will be transformed into a handle on a concrete loop instantiation by {@link #makeLoop}.
+ *
+ * @param init loop-local variable initializers.
+ * @param step bodies.
+ * @param pred predicates.
+ * @param fini finalizers.
+ * @param varSize number of loop-local variables.
+ * @param nArgs number of arguments passed to the loop.
+ * @param args arguments to the loop invocation.
+ *
+ * @return the result of executing the loop.
+ */
+ static Object looper(MethodHandle[] init, MethodHandle[] step, MethodHandle[] pred, MethodHandle[] fini,
+ int varSize, int nArgs, Object[] args) throws Throwable {
+ Object[] varsAndArgs = new Object[varSize + nArgs];
+ for (int i = 0, v = 0; i < init.length; ++i) {
+ if (init[i].type().returnType() == void.class) {
+ init[i].invoke(args);
+ } else {
+ varsAndArgs[v++] = init[i].invoke(args);
+ }
+ }
+ System.arraycopy(args, 0, varsAndArgs, varSize, nArgs);
+ final int nSteps = step.length;
+ for (; ; ) {
+ for (int i = 0, v = 0; i < nSteps; ++i) {
+ MethodHandle p = pred[i];
+ MethodHandle s = step[i];
+ MethodHandle f = fini[i];
+ if (s.type().returnType() == void.class) {
+ s.invoke(varsAndArgs);
+ } else {
+ varsAndArgs[v++] = s.invoke(varsAndArgs);
+ }
+ if (!(boolean) p.invoke(varsAndArgs)) {
+ return f.invoke(varsAndArgs);
+ }
+ }
+ }
+ }
+
+ /**
+ * This method is bound as the predicate in {@linkplain MethodHandles#countedLoop(MethodHandle, MethodHandle,
+ * MethodHandle) counting loops}.
+ *
+ * @param counter the counter parameter, passed in during loop execution.
+ * @param limit the upper bound of the parameter, statically bound at loop creation time.
+ *
+ * @return whether the counter has reached the limit.
+ */
+ static boolean countedLoopPredicate(int counter, int limit) {
+ return counter <= limit;
+ }
+
+ /**
+ * This method is bound as the step function in {@linkplain MethodHandles#countedLoop(MethodHandle, MethodHandle,
+ * MethodHandle) counting loops} to increment the counter.
+ *
+ * @param counter the loop counter.
+ *
+ * @return the loop counter incremented by 1.
+ */
+ static int countedLoopStep(int counter, int limit) {
+ return counter + 1;
+ }
+
+ /**
+ * This is bound to initialize the loop-local iterator in {@linkplain MethodHandles#iteratedLoop iterating loops}.
+ *
+ * @param it the {@link Iterable} over which the loop iterates.
+ *
+ * @return an {@link Iterator} over the argument's elements.
+ */
+ static Iterator> initIterator(Iterable> it) {
+ return it.iterator();
+ }
+
+ /**
+ * This method is bound as the predicate in {@linkplain MethodHandles#iteratedLoop iterating loops}.
+ *
+ * @param it the iterator to be checked.
+ *
+ * @return {@code true} iff there are more elements to iterate over.
+ */
+ static boolean iteratePredicate(Iterator> it) {
+ return it.hasNext();
+ }
+
+ /**
+ * This method is bound as the step for retrieving the current value from the iterator in {@linkplain
+ * MethodHandles#iteratedLoop iterating loops}.
+ *
+ * @param it the iterator.
+ *
+ * @return the next element from the iterator.
+ */
+ static Object iterateNext(Iterator> it) {
+ return it.next();
+ }
+
+ /**
+ * Makes a {@code try-finally} handle that conforms to the type constraints.
+ *
+ * @param target the target to execute in a {@code try-finally} block.
+ * @param cleanup the cleanup to execute in the {@code finally} block.
+ * @param type the result type of the entire construct.
+ * @param argTypes the types of the arguments.
+ *
+ * @return a handle on the constructed {@code try-finally} block.
+ */
+ static MethodHandle makeTryFinally(MethodHandle target, MethodHandle cleanup, Class> type, List> argTypes) {
+ MethodHandle tf = getConstantHandle(type == void.class ? MH_tryFinallyVoidExec : MH_tryFinallyExec);
+
+ // Bind the statically known arguments.
+ tf = MethodHandles.insertArguments(tf, 0, target, cleanup);
+
+ // Turn the args array into an argument list.
+ tf = tf.asCollector(Object[].class, argTypes.size());
+
+ // Finally, make try-finally type.
+ MethodType tfType = MethodType.methodType(type, argTypes);
+ tf = tf.asType(tfType);
+
+ return tf;
+ }
+
+ /**
+ * A method that will be bound during construction of a {@code try-finally} handle with non-{@code void} return type
+ * by {@link MethodHandles#tryFinally(MethodHandle, MethodHandle)}.
+ *
+ * @param target the handle to wrap in a {@code try-finally} block. This will be bound.
+ * @param cleanup the handle to run in any case before returning. This will be bound.
+ * @param args the arguments to the call. These will remain as the argument list.
+ *
+ * @return whatever the execution of the {@code target} returned (it may have been modified by the execution of
+ * {@code cleanup}).
+ * @throws Throwable in case anything is thrown by the execution of {@code target}, the {@link Throwable} will be
+ * passed to the {@code cleanup} handle, which may decide to throw any exception it sees fit.
+ */
+ static Object tryFinallyExecutor(MethodHandle target, MethodHandle cleanup, Object[] args) throws Throwable {
+ Throwable t = null;
+ Object r = null;
+ try {
+ r = target.invoke(args);
+ } catch (Throwable thrown) {
+ t = thrown;
+ throw t;
+ } finally {
+ r = cleanup.invoke(t, r, args);
+ }
+ return r;
+ }
+
+ /**
+ * A method that will be bound during construction of a {@code try-finally} handle with {@code void} return type by
+ * {@link MethodHandles#tryFinally(MethodHandle, MethodHandle)}.
+ *
+ * @param target the handle to wrap in a {@code try-finally} block. This will be bound.
+ * @param cleanup the handle to run in any case before returning. This will be bound.
+ * @param args the arguments to the call. These will remain as the argument list.
+ *
+ * @throws Throwable in case anything is thrown by the execution of {@code target}, the {@link Throwable} will be
+ * passed to the {@code cleanup} handle, which may decide to throw any exception it sees fit.
+ */
+ static void tryFinallyVoidExecutor(MethodHandle target, MethodHandle cleanup, Object[] args) throws Throwable {
+ Throwable t = null;
+ try {
+ target.invoke(args);
+ } catch (Throwable thrown) {
+ t = thrown;
+ throw t;
+ } finally {
+ cleanup.invoke(t, args);
+ }
+ }
+
// Indexes into constant method handles:
- private static final int
+ static final int
MH_cast = 0,
MH_selectAlternative = 1,
MH_copyAsPrimitiveArray = 2,
MH_fillNewTypedArray = 3,
MH_fillNewArray = 4,
MH_arrayIdentity = 5,
- MH_LIMIT = 6;
+ MH_looper = 6,
+ MH_countedLoopPred = 7,
+ MH_countedLoopStep = 8,
+ MH_iteratePred = 9,
+ MH_initIterator = 10,
+ MH_iterateNext = 11,
+ MH_tryFinallyExec = 12,
+ MH_tryFinallyVoidExec = 13,
+ MH_LIMIT = 14;
- private static MethodHandle getConstantHandle(int idx) {
+ static MethodHandle getConstantHandle(int idx) {
MethodHandle handle = HANDLES[idx];
if (handle != null) {
return handle;
@@ -1672,6 +1907,31 @@
return makeIntrinsic(IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "selectAlternative",
MethodType.methodType(MethodHandle.class, boolean.class, MethodHandle.class, MethodHandle.class)),
Intrinsic.SELECT_ALTERNATIVE);
+ case MH_looper:
+ return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "looper", MethodType.methodType(Object.class,
+ MethodHandle[].class, MethodHandle[].class, MethodHandle[].class, MethodHandle[].class,
+ int.class, int.class, Object[].class));
+ case MH_countedLoopPred:
+ return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "countedLoopPredicate",
+ MethodType.methodType(boolean.class, int.class, int.class));
+ case MH_countedLoopStep:
+ return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "countedLoopStep",
+ MethodType.methodType(int.class, int.class, int.class));
+ case MH_iteratePred:
+ return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "iteratePredicate",
+ MethodType.methodType(boolean.class, Iterator.class));
+ case MH_initIterator:
+ return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "initIterator",
+ MethodType.methodType(Iterator.class, Iterable.class));
+ case MH_iterateNext:
+ return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "iterateNext",
+ MethodType.methodType(Object.class, Iterator.class));
+ case MH_tryFinallyExec:
+ return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "tryFinallyExecutor",
+ MethodType.methodType(Object.class, MethodHandle.class, MethodHandle.class, Object[].class));
+ case MH_tryFinallyVoidExec:
+ return IMPL_LOOKUP.findStatic(MethodHandleImpl.class, "tryFinallyVoidExecutor",
+ MethodType.methodType(void.class, MethodHandle.class, MethodHandle.class, Object[].class));
}
} catch (ReflectiveOperationException ex) {
throw newInternalError(ex);
--- old/src/java.base/share/classes/java/lang/invoke/MethodHandles.java 2015-11-19 22:14:02.000000000 +0100
+++ new/src/java.base/share/classes/java/lang/invoke/MethodHandles.java 2015-11-19 22:14:02.000000000 +0100
@@ -26,10 +26,7 @@
package java.lang.invoke;
import java.lang.reflect.*;
-import java.util.BitSet;
-import java.util.List;
-import java.util.Arrays;
-import java.util.Objects;
+import java.util.*;
import sun.invoke.util.ValueConversions;
import sun.invoke.util.VerifyAccess;
@@ -39,11 +36,13 @@
import sun.reflect.misc.ReflectUtil;
import sun.security.util.SecurityConstants;
import java.lang.invoke.LambdaForm.BasicType;
-import static java.lang.invoke.LambdaForm.BasicType.*;
+
import static java.lang.invoke.MethodHandleStatics.*;
import static java.lang.invoke.MethodHandleImpl.Intrinsic;
import static java.lang.invoke.MethodHandleNatives.Constants.*;
import java.util.concurrent.ConcurrentHashMap;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
/**
* This class consists exclusively of static methods that operate on or return
@@ -176,7 +175,7 @@
* equivalent of a particular bytecode behavior.
* (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
* Here is a summary of the correspondence between these factory methods and
- * the behavior the resulting method handles:
+ * the behavior of the resulting method handles:
*
*
* Here, the type {@code C} is the class or interface being searched for a member,
@@ -255,6 +258,10 @@
* The names {@code aMethod}, {@code aField}, and {@code aConstructor} stand
* for reflective objects corresponding to the given members.
*
+ * The bytecode behavior for a {@code findClass} operation is a load of a constant class,
+ * as if by {@code ldc CONSTANT_Class}.
+ * The behavior is represented, not as a method handle, but directly as a {@code Class} constant.
+ *
* In cases where the given member is of variable arity (i.e., a method or constructor)
* the returned method handle will also be of {@linkplain MethodHandle#asVarargsCollector variable arity}.
* In all other cases, the returned method handle will be of fixed arity.
@@ -423,7 +430,7 @@
* and the Core Reflection API
* (as found on {@link java.lang.Class Class}).
*
- * If a security manager is present, member lookups are subject to
+ * If a security manager is present, member and class lookups are subject to
* additional checks.
* From one to three calls are made to the security manager.
* Any of these calls can refuse access by throwing a
@@ -433,6 +440,8 @@
* {@code refc} as the containing class in which the member
* is being sought, and {@code defc} as the class in which the
* member is actually defined.
+ * (If a class or other type is being accessed,
+ * the {@code refc} and {@code defc} values are the class itself.)
* The value {@code lookc} is defined as not present
* if the current lookup object does not have
* private access.
@@ -444,11 +453,16 @@
* then {@link SecurityManager#checkPackageAccess
* smgr.checkPackageAccess(refcPkg)} is called,
* where {@code refcPkg} is the package of {@code refc}.
- *
Step 2:
+ *
Step 2a:
* If the retrieved member is not public and
* {@code lookc} is not present, then
* {@link SecurityManager#checkPermission smgr.checkPermission}
* with {@code RuntimePermission("accessDeclaredMembers")} is called.
+ *
Step 2b:
+ * If the retrieved class has a {@code null} class loader,
+ * and {@code lookc} is not present, then
+ * {@link SecurityManager#checkPermission smgr.checkPermission}
+ * with {@code RuntimePermission("getClassLoader")} is called.
*
Step 3:
* If the retrieved member is not public,
* and if {@code lookc} is not present,
@@ -458,9 +472,9 @@
* where {@code defcPkg} is the package of {@code defc}.
*
* Security checks are performed after other access checks have passed.
- * Therefore, the above rules presuppose a member that is public,
+ * Therefore, the above rules presuppose a member or class that is public,
* or else that is being accessed from a lookup class that has
- * rights to access the member.
+ * rights to access the member or class.
*
*
Caller sensitive methods
* A small number of Java methods have a special property called caller sensitivity.
@@ -922,6 +936,49 @@
}
/**
+ * Looks up a class by name from the lookup context defined by this {@code Lookup} object. The static
+ * initializer of the class is not run.
+ *
+ * @param targetName the fully qualified name of the class to be looked up.
+ * @return the requested class.
+ * @exception SecurityException if a security manager is present and it
+ * refuses access
+ * @throws LinkageError if the linkage fails
+ * @throws ClassNotFoundException if the class does not exist.
+ * @throws IllegalAccessException if the class is not accessible, using the allowed access
+ * modes.
+ * @exception SecurityException if a security manager is present and it
+ * refuses access
+ * @since 9
+ */
+ public Class> findClass(String targetName) throws ClassNotFoundException, IllegalAccessException {
+ Class> targetClass = Class.forName(targetName, false, lookupClass.getClassLoader());
+ return accessClass(targetClass);
+ }
+
+ /**
+ * Determines if a class can be accessed from the lookup context defined by this {@code Lookup} object. The
+ * static initializer of the class is not run.
+ *
+ * @param targetClass the class to be access-checked
+ *
+ * @return the class that has been access-checked
+ *
+ * @throws IllegalAccessException if the class is not accessible from the lookup class, using the allowed access
+ * modes.
+ * @exception SecurityException if a security manager is present and it
+ * refuses access
+ * @since 9
+ */
+ public Class> accessClass(Class> targetClass) throws IllegalAccessException {
+ if (!VerifyAccess.isClassAccessible(targetClass, lookupClass, allowedModes)) {
+ throw new MemberName(targetClass).makeAccessException("access violation", this);
+ }
+ checkSecurityManager(targetClass, null);
+ return targetClass;
+ }
+
+ /**
* Produces an early-bound method handle for a virtual method.
* It will bypass checks for overriding methods on the receiver,
* as if called from an {@code invokespecial}
@@ -995,7 +1052,7 @@
*/
public MethodHandle findSpecial(Class> refc, String name, MethodType type,
Class> specialCaller) throws NoSuchMethodException, IllegalAccessException {
- checkSpecialCaller(specialCaller);
+ checkSpecialCaller(specialCaller, refc);
Lookup specialLookup = this.in(specialCaller);
MemberName method = specialLookup.resolveOrFail(REF_invokeSpecial, refc, name, type);
return specialLookup.getDirectMethod(REF_invokeSpecial, refc, method, findBoundCallerClass(method));
@@ -1224,7 +1281,7 @@
* @throws NullPointerException if any argument is null
*/
public MethodHandle unreflectSpecial(Method m, Class> specialCaller) throws IllegalAccessException {
- checkSpecialCaller(specialCaller);
+ checkSpecialCaller(specialCaller, null);
Lookup specialLookup = this.in(specialCaller);
MemberName method = new MemberName(m, true);
assert(method.isMethod());
@@ -1444,7 +1501,15 @@
ReflectUtil.checkPackageAccess(refc);
}
- // Step 2:
+ if (m == null) { // findClass or accessClass
+ // Step 2b:
+ if (!fullPowerLookup) {
+ smgr.checkPermission(SecurityConstants.GET_CLASSLOADER_PERMISSION);
+ }
+ return;
+ }
+
+ // Step 2a:
if (m.isPublic()) return;
if (!fullPowerLookup) {
smgr.checkPermission(SecurityConstants.CHECK_MEMBER_ACCESS_PERMISSION);
@@ -1557,11 +1622,13 @@
private static final boolean ALLOW_NESTMATE_ACCESS = false;
- private void checkSpecialCaller(Class> specialCaller) throws IllegalAccessException {
+ private void checkSpecialCaller(Class> specialCaller, Class> refc) throws IllegalAccessException {
int allowedModes = this.allowedModes;
if (allowedModes == TRUSTED) return;
if (!hasPrivateAccess()
|| (specialCaller != lookupClass()
+ // ensure non-abstract methods in superinterfaces can be special-invoked
+ && !(refc != null && refc.isInterface() && refc.isAssignableFrom(specialCaller))
&& !(ALLOW_NESTMATE_ACCESS &&
VerifyAccess.isSamePackageMember(specialCaller, lookupClass()))))
throw new MemberName(specialCaller).
@@ -1888,7 +1955,7 @@
MethodHandle spreadInvoker(MethodType type, int leadingArgCount) {
if (leadingArgCount < 0 || leadingArgCount > type.parameterCount())
throw newIllegalArgumentException("bad argument count", leadingArgCount);
- type = type.asSpreaderType(Object[].class, type.parameterCount() - leadingArgCount);
+ type = type.asSpreaderType(Object[].class, leadingArgCount, type.parameterCount() - leadingArgCount);
return type.invokers().spreadInvoker(leadingArgCount);
}
@@ -2924,19 +2991,7 @@
*/
public static
MethodHandle foldArguments(MethodHandle target, MethodHandle combiner) {
- int foldPos = 0;
- MethodType targetType = target.type();
- MethodType combinerType = combiner.type();
- Class> rtype = foldArgumentChecks(foldPos, targetType, combinerType);
- BoundMethodHandle result = target.rebind();
- boolean dropResult = (rtype == void.class);
- // Note: This may cache too many distinct LFs. Consider backing off to varargs code.
- LambdaForm lform = result.editor().foldArgumentsForm(1 + foldPos, dropResult, combinerType.basicType());
- MethodType newType = targetType;
- if (!dropResult)
- newType = newType.dropParameterTypes(foldPos, foldPos + 1);
- result = result.copyWithExtendL(newType, lform, combiner);
- return result;
+ return foldArguments(target, 0, combiner);
}
private static Class> foldArgumentChecks(int foldPos, MethodType targetType, MethodType combinerType) {
@@ -2949,7 +3004,7 @@
.equals(targetType.parameterList().subList(afterInsertPos,
afterInsertPos + foldArgs))))
ok = false;
- if (ok && foldVals != 0 && combinerType.returnType() != targetType.parameterType(0))
+ if (ok && foldVals != 0 && combinerType.returnType() != targetType.parameterType(foldPos))
ok = false;
if (!ok)
throw misMatchedTypes("target and combiner types", targetType, combinerType);
@@ -3011,7 +3066,7 @@
return MethodHandleImpl.makeGuardWithTest(test, target, fallback);
}
- static RuntimeException misMatchedTypes(String what, MethodType t1, MethodType t2) {
+ static RuntimeException misMatchedTypes(String what, T t1, T t2) {
return newIllegalArgumentException(what + " must match: " + t1 + " != " + t2);
}
@@ -3057,6 +3112,7 @@
* the given exception type, or if the method handle types do
* not match in their return types and their
* corresponding parameters
+ * @see MethodHandles#tryFinally(MethodHandle, MethodHandle)
*/
public static
MethodHandle catchException(MethodHandle target,
@@ -3100,4 +3156,897 @@
throw new ClassCastException(exType.getName());
return MethodHandleImpl.throwException(MethodType.methodType(returnType, exType));
}
+
+ /**
+ * Constructs a method handle representing a loop with several loop variables that are updated and checked upon each
+ * iteration. Upon termination of the loop due to one of the predicates, a corresponding finalizer is run and
+ * delivers the loop's result, which is the return value of the resulting handle.
+ *
+ * Intuitively, every loop is formed by one or more "clauses", each specifying a local iteration value and/or a loop
+ * exit. Each iteration of the loop executes each clause in order. A clause can optionally update its iteration
+ * variable; it can also optionally perform a test and conditional loop exit. In order to express this logic in
+ * terms of method handles, each clause will determine four actions:
+ *
Before the loop executes, the initialization of an iteration variable or loop invariant local.
+ *
When a clause executes, an update step for the iteration variable.
+ *
When a clause executes, a predicate execution to test for loop exit.
+ *
If a clause causes a loop exit, a finalizer execution to compute the loop's return value.
+ *
+ *
+ * Some of these clause parts may be omitted according to certain rules, and useful default behavior is provided in
+ * this case. See below for a detailed description.
+ *
+ * Each clause function, with the exception of clause initializers, is able to observe the entire loop state,
+ * because it will be passed all current iteration variable values, as well as all incoming loop
+ * parameters. Most clause functions will not need all of this information, but they will be formally connected as
+ * if by {@link #dropArguments}.
+ *
+ * Given a set of clauses, there is a number of checks and adjustments performed to connect all the parts of the
+ * loop. They are spelled out in detail in the steps below. In these steps, every occurrence of the word "must"
+ * corresponds to a place where {@link IllegalArgumentException} may be thrown if the required constraint is not met
+ * by the inputs to the loop combinator. The term "effectively identical", applied to parameter type lists, means
+ * that they must be identical, or else one list must be a proper prefix of the other.
+ *
+ * Step 0: Determine clause structure.
+ *
The clause array (of type {@code MethodHandle[][]} must be non-{@code null} and contain at least one element.
+ *
The clause array may not contain {@code null}s or sub-arrays longer than four elements.
+ *
Clauses shorter than four elements are treated as if they were padded by {@code null} elements to length
+ * four. Padding takes place by appending elements to the array.
+ *
Clauses with all {@code null}s are disregarded.
+ *
Each clause is treated as a four-tuple of functions, called "init", "step", "pred", and "fini".
+ *
+ *
+ * Step 1A: Determine iteration variables.
+ *
Examine init and step function return types, pairwise, to determine each clause's iteration variable type.
+ *
If both functions are omitted, use {@code void}; else if one is omitted, use the other's return type; else
+ * use the common return type (they must be identical).
+ *
Form the list of return types (in clause order), omitting all occurrences of {@code void}.
+ *
This list of types is called the "common prefix".
+ *
+ *
+ * Step 1B: Determine loop parameters.
+ *
Examine init function parameter lists.
+ *
Omitted init functions are deemed to have {@code null} parameter lists.
+ *
All init function parameter lists must be effectively identical.
+ *
The longest parameter list (which is necessarily unique) is called the "common suffix".
+ *
+ *
+ * Step 1C: Determine loop return type.
+ *
Examine fini function return types, disregarding omitted fini functions.
+ *
If there are no fini functions, use {@code void} as the loop return type.
+ *
Otherwise, use the common return type of the fini functions; they must all be identical.
+ *
+ *
+ * Step 1D: Check other types.
+ *
There must be at least one non-omitted pred function.
+ *
Every non-omitted pred function must have a {@code boolean} return type.
+ *
+ *
+ * (Implementation Note: Steps 1A, 1B, 1C, 1D are logically independent of each other, and may be performed in any
+ * order.)
+ *
+ * Step 2: Determine parameter lists.
+ *
The parameter list for the resulting loop handle will be the "common suffix".
+ *
The parameter list for init functions will be adjusted to the "common suffix". (Note that their parameter
+ * lists are already effectively identical to the common suffix.)
+ *
The parameter list for non-init (step, pred, and fini) functions will be adjusted to the common prefix
+ * followed by the common suffix, called the "common parameter sequence".
+ *
Every non-init, non-omitted function parameter list must be effectively identical to the common parameter
+ * sequence.
+ *
+ *
+ * Step 3: Fill in omitted functions.
+ *
If an init function is omitted, use a {@linkplain #constant constant function} of the appropriate
+ * {@code null}/zero/{@code false}/{@code void} type. (For this purpose, a constant {@code void} is simply a
+ * function which does nothing and returns {@code void}; it can be obtained from another constant function by
+ * {@linkplain MethodHandle#asType type conversion}.)
+ *
If a step function is omitted, use an {@linkplain #identity identity function} of the clause's iteration
+ * variable type; insert dropped argument parameters before the identity function parameter for the non-{@code void}
+ * iteration variables of preceding clauses. (This will turn the loop variable into a local loop invariant.)
+ *
If a pred function is omitted, the corresponding fini function must also be omitted.
+ *
If a pred function is omitted, use a constant {@code true} function. (This will keep the loop going, as far
+ * as this clause is concerned.)
+ *
If a fini function is omitted, use a constant {@code null}/zero/{@code false}/{@code void} function of the
+ * loop return type.
+ *
+ *
+ * Step 4: Fill in missing parameter types.
+ *
At this point, every init function parameter list is effectively identical to the common suffix, but some
+ * lists may be shorter. For every init function with a short parameter list, pad out the end of the list by
+ * {@linkplain #dropArguments dropping arguments}.
+ *
At this point, every non-init function parameter list is effectively identical to the common parameter
+ * sequence, but some lists may be shorter. For every non-init function with a short parameter list, pad out the end
+ * of the list by {@linkplain #dropArguments dropping arguments}.
+ *
+ *
+ * Final observations.
+ *
After these steps, all clauses have been adjusted by supplying omitted functions and arguments.
+ *
All init functions have a common parameter type list, which the final loop handle will also have.
+ *
All fini functions have a common return type, which the final loop handle will also have.
+ *
All non-init functions have a common parameter type list, which is the common parameter sequence, of
+ * (non-{@code void}) iteration variables followed by loop parameters.
+ *
Each pair of init and step functions agrees in their return types.
+ *
Each non-init function will be able to observe the current values of all iteration variables, by means of the
+ * common prefix.
+ *
+ *
+ * Loop execution.
+ *
When the loop is called, the loop input values are saved in locals, to be passed (as the common suffix) to
+ * every clause function. These locals are loop invariant.
+ *
Each init function is executed in clause order (passing the common suffix) and the non-{@code void} values
+ * are saved (as the common prefix) into locals. These locals are loop varying (unless their steps are identity
+ * functions, as noted above).
+ *
All function executions (except init functions) will be passed the common parameter sequence, consisting of
+ * the non-{@code void} iteration values (in clause order) and then the loop inputs (in argument order).
+ *
The step and pred functions are then executed, in clause order (step before pred), until a pred function
+ * returns {@code false}.
+ *
The non-{@code void} result from a step function call is used to update the corresponding loop variable. The
+ * updated value is immediately visible to all subsequent function calls.
+ *
If a pred function returns {@code false}, the corresponding fini function is called, and the resulting value
+ * is returned from the loop as a whole.
+ *
+ *
+ * Here is pseudocode for the resulting loop handle:
+ *
{@code
+ * // iterative implementation of the factorial function as a loop handle
+ * static int one(int k) { return 1; }
+ * int inc(int i, int acc, int k) { return i + 1; }
+ * int mult(int i, int acc, int k) { return i * acc; }
+ * boolean pred(int i, int acc, int k) { return i < k; }
+ * int fin(int i, int acc, int k) { return acc; }
+ * // assume MH_one, MH_inc, MH_mult, MH_pred, and MH_fin are handles to the above methods
+ * // null initializer for counter, should initialize to 0
+ * MethodHandle[] counterClause = new MethodHandle[]{null, MH_inc};
+ * MethodHandle[] accumulatorClause = new MethodHandle[]{MH_one, MH_mult, MH_pred, MH_fin};
+ * MethodHandle loop = MethodHandles.loop(counterClause, accumulatorClause);
+ * assertEquals(120, loop.invoke(5));
+ * }
+ *
+ * @param clauses an array of arrays (4-tuples) of {@link MethodHandle}s adhering to the rules described above.
+ *
+ * @return a method handle embodying the looping behavior as defined by the arguments.
+ *
+ * @throws IllegalArgumentException in case any of the constraints described above is violated.
+ *
+ * @see MethodHandles#whileLoop(MethodHandle, MethodHandle, MethodHandle)
+ * @see MethodHandles#doWhileLoop(MethodHandle, MethodHandle, MethodHandle)
+ * @see MethodHandles#countedLoop(MethodHandle, MethodHandle, MethodHandle)
+ * @see MethodHandles#iteratedLoop(MethodHandle, MethodHandle, MethodHandle)
+ * @since 9
+ */
+ public static MethodHandle loop(MethodHandle[]... clauses) {
+ // Step 0: determine clause structure.
+ checkLoop0(clauses);
+
+ List init = new ArrayList<>();
+ List step = new ArrayList<>();
+ List pred = new ArrayList<>();
+ List fini = new ArrayList<>();
+
+ Stream.of(clauses).filter(c -> Stream.of(c).anyMatch(Objects::nonNull)).forEach(clause -> {
+ init.add(clause[0]); // all clauses have at least length 1
+ step.add(clause.length <= 1 ? null : clause[1]);
+ pred.add(clause.length <= 2 ? null : clause[2]);
+ fini.add(clause.length <= 3 ? null : clause[3]);
+ });
+
+ assert Stream.of(init, step, pred, fini).map(List::size).distinct().count() == 1;
+ final int nclauses = init.size();
+
+ // Step 1A: determine iteration variables.
+ final List> iterationVariableTypes = new ArrayList<>();
+ for (int i = 0; i < nclauses; ++i) {
+ MethodHandle in = init.get(i);
+ MethodHandle st = step.get(i);
+ if (in == null && st == null) {
+ iterationVariableTypes.add(void.class);
+ } else if (in != null && st != null) {
+ checkLoop1a(i, in, st);
+ iterationVariableTypes.add(in.type().returnType());
+ } else {
+ iterationVariableTypes.add(in == null ? st.type().returnType() : in.type().returnType());
+ }
+ }
+ final List> commonPrefix = iterationVariableTypes.stream().filter(t -> t != void.class).
+ collect(Collectors.toList());
+
+ // Step 1B: determine loop parameters.
+ final List> empty = new ArrayList<>();
+ final List> commonSuffix = init.stream().filter(Objects::nonNull).map(MethodHandle::type).
+ map(MethodType::parameterList).reduce((p, q) -> p.size() >= q.size() ? p : q).orElse(empty);
+ checkLoop1b(init, commonSuffix);
+
+ // Step 1C: determine loop return type.
+ // Step 1D: check other types.
+ final Class> loopReturnType = fini.stream().filter(Objects::nonNull).map(MethodHandle::type).
+ map(MethodType::returnType).findFirst().orElse(void.class);
+ checkLoop1cd(pred, fini, loopReturnType);
+
+ // Step 2: determine parameter lists.
+ final List> commonParameterSequence = new ArrayList<>(commonPrefix);
+ commonParameterSequence.addAll(commonSuffix);
+ checkLoop2(step, pred, fini, commonParameterSequence);
+
+ // Step 3: fill in omitted functions.
+ for (int i = 0; i < nclauses; ++i) {
+ Class> t = iterationVariableTypes.get(i);
+ if (init.get(i) == null) {
+ init.set(i, zeroHandle(t));
+ }
+ if (step.get(i) == null) {
+ step.set(i, dropArguments(t == void.class ? zeroHandle(t) : identity(t), 0, commonPrefix.subList(0, i)));
+ }
+ if (pred.get(i) == null) {
+ pred.set(i, constant(boolean.class, true));
+ }
+ if (fini.get(i) == null) {
+ fini.set(i, zeroHandle(t));
+ }
+ }
+
+ // Step 4: fill in missing parameter types.
+ List finit = fillParameterTypes(init, commonSuffix);
+ List fstep = fillParameterTypes(step, commonParameterSequence);
+ List fpred = fillParameterTypes(pred, commonParameterSequence);
+ List ffini = fillParameterTypes(fini, commonParameterSequence);
+
+ assert finit.stream().map(MethodHandle::type).map(MethodType::parameterList).
+ allMatch(pl -> pl.equals(commonSuffix));
+ assert Stream.of(fstep, fpred, ffini).flatMap(List::stream).map(MethodHandle::type).map(MethodType::parameterList).
+ allMatch(pl -> pl.equals(commonParameterSequence));
+
+ return MethodHandleImpl.makeLoop(loopReturnType, commonSuffix, commonPrefix, finit, fstep, fpred, ffini);
+ }
+
+ private static List fillParameterTypes(List hs, final List> targetParams) {
+ return hs.stream().map(h -> {
+ int pc = h.type().parameterCount();
+ int tpsize = targetParams.size();
+ return pc < tpsize ? dropArguments(h, pc, targetParams.subList(pc, tpsize)) : h;
+ }).collect(Collectors.toList());
+ }
+
+ /**
+ * Constructs a {@code while} loop from an initializer, a body, and a predicate. This is a convenience wrapper for
+ * the {@linkplain #loop(MethodHandle[][]) generic loop combinator}.
+ *
+ * The loop handle's result type is the same as the sole loop variable's, i.e., the result type of {@code init}.
+ * The parameter type list of {@code init} also determines that of the resulting handle. The {@code pred} handle
+ * must have an additional leading parameter of the same type as {@code init}'s result, and so must the {@code
+ * body}. These constraints follow directly from those described for the {@linkplain MethodHandles#loop(MethodHandle[][])
+ * generic loop combinator}.
+ *
+ * Here is pseudocode for the resulting loop handle:
+ *
{@code
+ * V init(A);
+ * boolean pred(V, A);
+ * V body(V, A);
+ * V whileLoop(A a) {
+ * V v = init(a);
+ * while (pred(v, a)) {
+ * v = body(v, a);
+ * }
+ * return v;
+ * }
+ * }
+ *
+ * @apiNote Example:
+ *
{@code
+ * // implement the zip function for lists as a loop handle
+ * List initZip(Iterator a, Iterator b) { return new ArrayList<>(); }
+ * boolean zipPred(List zip, Iterator a, Iterator b) { return a.hasNext() && b.hasNext(); }
+ * List zipStep(List zip, Iterator a, Iterator b) {
+ * zip.add(a.next());
+ * zip.add(b.next());
+ * return zip;
+ * }
+ * // assume MH_initZip, MH_zipPred, and MH_zipStep are handles to the above methods
+ * MethodHandle loop = MethodHandles.doWhileLoop(MH_initZip, MH_zipPred, MH_zipStep);
+ * List a = Arrays.asList("a", "b", "c", "d");
+ * List b = Arrays.asList("e", "f", "g", "h");
+ * List zipped = Arrays.asList("a", "e", "b", "f", "c", "g", "d", "h");
+ * assertEquals(zipped, (List) loop.invoke(a.iterator(), b.iterator()));
+ * }
+ *
+ *
+ * The implementation of this method is equivalent to:
+ *
+ *
+ * @param init initializer: it should provide the initial value of the loop variable. This controls the loop's
+ * result type. Passing {@code null} or a {@code void} init function will make the loop's result type
+ * {@code void}.
+ * @param pred condition for the loop, which may not be {@code null}.
+ * @param body body of the loop, which may not be {@code null}.
+ *
+ * @return the value of the loop variable as the loop terminates.
+ * @throws IllegalArgumentException if any argument has a type inconsistent with the loop structure
+ *
+ * @see MethodHandles#loop(MethodHandle[][])
+ * @since 9
+ */
+ public static MethodHandle whileLoop(MethodHandle init, MethodHandle pred, MethodHandle body) {
+ MethodHandle fin = init == null ? zeroHandle(void.class) : identity(init.type().returnType());
+ MethodHandle[] checkExit = {null, null, pred, fin};
+ MethodHandle[] varBody = {init, body};
+ return loop(checkExit, varBody);
+ }
+
+ /**
+ * Constructs a {@code do-while} loop from an initializer, a body, and a predicate. This is a convenience wrapper
+ * for the {@linkplain MethodHandles#loop(MethodHandle[][]) generic loop combinator}.
+ *
+ * The loop handle's result type is the same as the sole loop variable's, i.e., the result type of {@code init}.
+ * The parameter type list of {@code init} also determines that of the resulting handle. The {@code pred} handle
+ * must have an additional leading parameter of the same type as {@code init}'s result, and so must the {@code
+ * body}. These constraints follow directly from those described for the {@linkplain MethodHandles#loop(MethodHandle[][])
+ * generic loop combinator}.
+ *
+ * Here is pseudocode for the resulting loop handle:
+ *
{@code
+ * V init(A);
+ * boolean pred(V, A);
+ * V body(V, A);
+ * V doWhileLoop(A a) {
+ * V v = init(a);
+ * do {
+ * v = body(v, a);
+ * } while (pred(v, a));
+ * return v;
+ * }
+ * }
+ *
+ * @apiNote Example:
+ *
{@code
+ * // int i = 0; while (i < limit) { ++i; } return i; => limit
+ * int zero(int limit) { return 0; }
+ * int step(int i, int limit) { return i + 1; }
+ * boolean pred(int i, int limit) { return i < limit; }
+ * // assume MH_zero, MH_step, and MH_pred are handles to the above methods
+ * MethodHandle loop = MethodHandles.doWhileLoop(MH_zero, MH_step, MH_pred);
+ * assertEquals(23, loop.invoke(23));
+ * }
+ *
+ * *
+ * The implementation of this method is equivalent to:
+ *
+ *
+ *
+ * @param init initializer: it should provide the initial value of the loop variable. This controls the loop's
+ * result type. Passing {@code null} or a {@code void} init function will make the loop's result type
+ * {@code void}.
+ * @param pred condition for the loop, which may not be {@code null}.
+ * @param body body of the loop, which may not be {@code null}.
+ *
+ * @return the value of the loop variable as the loop terminates.
+ * @throws IllegalArgumentException if any argument has a type inconsistent with the loop structure
+ *
+ * @see MethodHandles#loop(MethodHandle[][])
+ * @since 9
+ */
+ public static MethodHandle doWhileLoop(MethodHandle init, MethodHandle body, MethodHandle pred) {
+ MethodHandle fin = init == null ? zeroHandle(void.class) : identity(init.type().returnType());
+ MethodHandle[] clause = {init, body, pred, fin};
+ return loop(clause);
+ }
+
+ /**
+ * Constructs a loop that runs a given number of iterations. The loop counter is an {@code int} initialized from the
+ * {@code iterations} handle evaluation result. The counter is passed to the {@code body} function, so that must
+ * accept an initial {@code int} argument. The result of the loop execution is the final value of the additional
+ * local state. This is a convenience wrapper for the {@linkplain MethodHandles#loop(MethodHandle[][]) generic loop combinator}.
+ *
+ * The result type and parameter type list of {@code init} determine those of the resulting handle. The {@code
+ * iterations} handle must accept the same parameter types as {@code init} but return an {@code int}. The {@code
+ * body} handle must accept the same parameter types as well, preceded by an {@code int} parameter for the counter,
+ * and a parameter of the same type as {@code init}'s result. These constraints follow directly from those described
+ * for the {@linkplain MethodHandles#loop(MethodHandle[][]) generic loop combinator}.
+ *
+ * Here is pseudocode for the resulting loop handle:
+ *
{@code
+ * int iterations(A);
+ * V init(A);
+ * V body(int, V, A);
+ * V countedLoop(A a) {
+ * int end = iterations(a);
+ * V v = init(a);
+ * for (int i = 0; i < end; ++i) {
+ * v = body(i, v, a);
+ * }
+ * return v;
+ * }
+ * }
+ *
+ * @apiNote Example:
+ *
{@code
+ * // String s = "Lambdaman!"; for (int i = 0; i < 13; ++i) { s = "na " + s; } return s;
+ * // => a variation on a well known theme
+ * String start(String arg) { return arg; }
+ * String step(int counter, String v, String arg) { return "na " + v; }
+ * // assume MH_start and MH_step are handles to the two methods above
+ * MethodHandle loop = MethodHandles.countedLoop(13, MH_start, MH_step);
+ * assertEquals("na na na na na na na na na na na na na Lambdaman!", loop.invoke("Lambdaman!"));
+ * }
+ *
+ *
+ * The implementation of this method is equivalent to:
+ *
+ *
+ * @param iterations a handle to return the number of iterations this loop should run.
+ * @param init initializer for additional loop state. This determines the loop's result type.
+ * Passing {@code null} or a {@code void} init function will make the loop's result type
+ * {@code void}.
+ * @param body the body of the loop, which must not be {@code null}.
+ * It must accept an initial {@code int} parameter (for the counter), and then any
+ * additional loop-local variable plus loop parameters.
+ *
+ * @return a method handle representing the loop.
+ * @throws IllegalArgumentException if any argument has a type inconsistent with the loop structure
+ *
+ * @since 9
+ */
+ public static MethodHandle countedLoop(MethodHandle iterations, MethodHandle init, MethodHandle body) {
+ return countedLoop(null, iterations, init, body);
+ }
+
+ /**
+ * Constructs a loop that counts over a range of numbers. The loop counter is an {@code int} that will be
+ * initialized to the {@code int} value returned from the evaluation of the {@code start} handle and run to the
+ * value returned from {@code end} (exclusively) with a step width of 1. The counter value is passed to the {@code
+ * body} function in each iteration; it has to accept an initial {@code int} parameter
+ * for that. The result of the loop execution is the final value of the additional local state
+ * obtained by running {@code init}.
+ * This is a
+ * convenience wrapper for the {@linkplain MethodHandles#loop(MethodHandle[][]) generic loop combinator}.
+ *
+ * The constraints for the {@code init} and {@code body} handles are the same as for {@link
+ * #countedLoop(MethodHandle, MethodHandle, MethodHandle)}. Additionally, the {@code start} and {@code end} handles
+ * must return an {@code int} and accept the same parameters as {@code init}.
+ *
+ * Here is pseudocode for the resulting loop handle:
+ *
{@code
+ * int start(A);
+ * int end(A);
+ * V init(A);
+ * V body(int, V, A);
+ * V countedLoop(A a) {
+ * int s = start(a);
+ * int e = end(a);
+ * V v = init(a);
+ * for (int i = s; i < e; ++i) {
+ * v = body(i, v, a);
+ * }
+ * return v;
+ * }
+ * }
+ *
+ *
+ * The implementation of this method is equivalent to:
+ *
{@code
+ * MethodHandle countedLoop(MethodHandle start, MethodHandle end, MethodHandle init, MethodHandle body) {
+ * MethodHandle returnVar = dropArguments(identity(init.type().returnType()), 0, int.class, int.class);
+ * // assume MH_increment and MH_lessThan are handles to x+1 and x
+ *
+ * @param start a handle to return the start value of the loop counter.
+ * If it is {@code null}, a constant zero is assumed.
+ * @param end a non-{@code null} handle to return the end value of the loop counter (the loop will run to {@code end-1}).
+ * @param init initializer for additional loop state. This determines the loop's result type.
+ * Passing {@code null} or a {@code void} init function will make the loop's result type
+ * {@code void}.
+ * @param body the body of the loop, which must not be {@code null}.
+ * It must accept an initial {@code int} parameter (for the counter), and then any
+ * additional loop-local variable plus loop parameters.
+ *
+ * @return a method handle representing the loop.
+ * @throws IllegalArgumentException if any argument has a type inconsistent with the loop structure
+ *
+ * @since 9
+ */
+ public static MethodHandle countedLoop(MethodHandle start, MethodHandle end, MethodHandle init, MethodHandle body) {
+ MethodHandle returnVar = dropArguments(init == null ? zeroHandle(void.class) : identity(init.type().returnType()),
+ 0, int.class, int.class);
+ MethodHandle[] indexVar = {start, MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_countedLoopStep)};
+ MethodHandle[] loopLimit = {end, null, MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_countedLoopPred), returnVar};
+ MethodHandle[] bodyClause = {init, dropArguments(body, 1, int.class)};
+ return loop(indexVar, loopLimit, bodyClause);
+ }
+
+ /**
+ * Constructs a loop that ranges over the elements produced by an {@code Iterator}.
+ * The iterator will be produced by the evaluation of the {@code iterator} handle.
+ * If this handle is passed as {@code null} the method {@link Iterable#iterator} will be used instead,
+ * and will be applied to a leading argument of the loop handle.
+ * Each value produced by the iterator is passed to the {@code body}, which must accept an initial {@code T} parameter.
+ * The result of the loop execution is the final value of the additional local state
+ * obtained by running {@code init}.
+ *
+ * This is a convenience wrapper for the
+ * {@linkplain MethodHandles#loop(MethodHandle[][]) generic loop combinator}, and the constraints imposed on the {@code body}
+ * handle follow directly from those described for the latter.
+ *
+ * Here is pseudocode for the resulting loop handle:
+ *
{@code
+ * Iterator iterator(A); // defaults to Iterable::iterator
+ * V init(A);
+ * V body(T,V,A);
+ * V iteratedLoop(A a) {
+ * Iterator it = iterator(a);
+ * V v = init(a);
+ * for (T t : it) {
+ * v = body(t, v, a);
+ * }
+ * return v;
+ * }
+ * }
+ *
+ * The type {@code T} may be either a primitive or reference.
+ * Since type {@code Iterator} is erased in the method handle representation to the raw type
+ * {@code Iterator}, the {@code iteratedLoop} combinator adjusts the leading argument type for {@code body}
+ * to {@code Object} as if by the {@link MethodHandle#asType asType} conversion method.
+ * Therefore, if an iterator of the wrong type appears as the loop is executed,
+ * runtime exceptions may occur as the result of dynamic conversions performed by {@code asType}.
+ *
+ * @apiNote Example:
+ *
{@code
+ * // reverse a list
+ * List reverseStep(String e, List r) {
+ * r.add(0, e);
+ * return r;
+ * }
+ * List newArrayList() { return new ArrayList<>(); }
+ * // assume MH_reverseStep, MH_newArrayList are handles to the above methods
+ * MethodHandle loop = MethodHandles.iteratedLoop(null, MH_newArrayList, MH_reverseStep);
+ * List list = Arrays.asList("a", "b", "c", "d", "e");
+ * List reversedList = Arrays.asList("e", "d", "c", "b", "a");
+ * assertEquals(reversedList, (List) loop.invoke(list));
+ * }
+ *
+ * The implementation of this method is equivalent to:
+ *
+ *
+ * @param iterator a handle to return the iterator to start the loop.
+ * Passing {@code null} will make the loop call {@link Iterable#iterator()} on the first
+ * incoming value.
+ * @param init initializer for additional loop state. This determines the loop's result type.
+ * Passing {@code null} or a {@code void} init function will make the loop's result type
+ * {@code void}.
+ * @param body the body of the loop, which must not be {@code null}.
+ * It must accept an initial {@code T} parameter (for the iterated values), and then any
+ * additional loop-local variable plus loop parameters.
+ *
+ * @return a method handle embodying the iteration loop functionality.
+ * @throws IllegalArgumentException if any argument has a type inconsistent with the loop structure
+ *
+ * @since 9
+ */
+ public static MethodHandle iteratedLoop(MethodHandle iterator, MethodHandle init, MethodHandle body) {
+ checkIteratedLoop(body);
+
+ MethodHandle initit = MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_initIterator);
+ MethodHandle initIterator = iterator == null ?
+ initit.asType(initit.type().changeParameterType(0, body.type().parameterType(init == null ? 1 : 2))) :
+ iterator;
+ Class> itype = initIterator.type().returnType();
+ Class> ttype = body.type().parameterType(0);
+
+ MethodHandle returnVar =
+ dropArguments(init == null ? zeroHandle(void.class) : identity(init.type().returnType()), 0, itype);
+ MethodHandle initnx = MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_iterateNext);
+ MethodHandle nextVal = initnx.asType(initnx.type().changeReturnType(ttype));
+
+ MethodHandle[] iterVar = {initIterator, null, MethodHandleImpl.getConstantHandle(MethodHandleImpl.MH_iteratePred), returnVar};
+ MethodHandle[] bodyClause = {init, filterArgument(body, 0, nextVal)};
+
+ return loop(iterVar, bodyClause);
+ }
+
+ /**
+ * Makes a method handle that adapts a {@code target} method handle by wrapping it in a {@code try-finally} block.
+ * Another method handle, {@code cleanup}, represents the functionality of the {@code finally} block. Any exception
+ * thrown during the execution of the {@code target} handle will be passed to the {@code cleanup} handle. The
+ * exception will be rethrown, unless {@code cleanup} handle throws an exception first. The
+ * value returned from the {@code cleanup} handle's execution will be the result of the execution of the
+ * {@code try-finally} handle.
+ *
+ * The {@code cleanup} handle will be passed one or two additional leading arguments.
+ * The first is the exception thrown during the
+ * execution of the {@code target} handle, or {@code null} if no exception was thrown.
+ * The second is the result of the execution of the {@code target} handle, or, if it throws an exception,
+ * a {@code null}, zero, or {@code false} value of the required type is supplied as a placeholder.
+ * The second argument is not present if the {@code target} handle has a {@code void} return type.
+ * (Note that, except for argument type conversions, combinators represent {@code void} values in parameter lists
+ * by omitting the corresponding paradoxical arguments, not by inserting {@code null} or zero values.)
+ *
+ * The {@code target} and {@code cleanup} handles' return types must be the same. Their parameter type lists also
+ * must be the same, but the {@code cleanup} handle must accept one or two more leading parameters:
+ *
a {@code Throwable}, which will carry the exception thrown by the {@code target} handle (if any); and
+ *
a parameter of the same type as the return type of both {@code target} and {@code cleanup}, which will carry
+ * the result from the execution of the {@code target} handle.
+ * This parameter is not present if the {@code target} returns {@code void}.
+ *
+ *
+ * The pseudocode for the resulting adapter looks like this:
+ *
{@code
+ * T target(A..., B...);
+ * T cleanup(Throwable, T, A...);
+ * T adapter(A... a, B... b) {
+ * T result = (zero value for T);
+ * Throwable throwable = null;
+ * try {
+ * result = target(a..., b...);
+ * } catch (Throwable t) {
+ * throwable = t;
+ * throw t;
+ * } finally {
+ * result = cleanup(throwable, result, a...);
+ * }
+ * return result;
+ * }
+ * }
+ *
+ * Note that the saved arguments ({@code a...} in the pseudocode) cannot
+ * be modified by execution of the target, and so are passed unchanged
+ * from the caller to the cleanup, if it is invoked.
+ *
+ * The target and cleanup must return the same type, even if the cleanup
+ * always throws.
+ * To create such a throwing cleanup, compose the cleanup logic
+ * with {@link #throwException throwException},
+ * in order to create a method handle of the correct return type.
+ *
+ * Note that {@code tryFinally} never converts exceptions into normal returns.
+ * In rare cases where exceptions must be converted in that way, first wrap
+ * the target with {@link #catchException(MethodHandle, Class, MethodHandle)}
+ * to capture an outgoing exception, and then wrap with {@code tryFinally}.
+ *
+ * @param target the handle whose execution is to be wrapped in a {@code try} block.
+ * @param cleanup the handle that is invoked in the finally block.
+ *
+ * @return a method handle embodying the {@code try-finally} block composed of the two arguments.
+ * @throws NullPointerException if any argument is null
+ * @throws IllegalArgumentException if {@code cleanup} does not accept
+ * the required leading arguments, or if the method handle types do
+ * not match in their return types and their
+ * corresponding trailing parameters
+ *
+ * @see MethodHandles#catchException(MethodHandle, Class, MethodHandle)
+ * @since 9
+ */
+ public static MethodHandle tryFinally(MethodHandle target, MethodHandle cleanup) {
+ List> targetParamTypes = target.type().parameterList();
+ List> cleanupParamTypes = cleanup.type().parameterList();
+ Class> rtype = target.type().returnType();
+
+ checkTryFinally(target, cleanup);
+
+ // Match parameter lists: if the cleanup has a shorter parameter list than the target, add ignored arguments.
+ int tpSize = targetParamTypes.size();
+ int cpPrefixLength = rtype == void.class ? 1 : 2;
+ int cpSize = cleanupParamTypes.size();
+ MethodHandle aCleanup = cpSize - cpPrefixLength < tpSize ?
+ dropArguments(cleanup, cpSize, targetParamTypes.subList(tpSize - (cpSize - cpPrefixLength), tpSize)) :
+ cleanup;
+
+ MethodHandle aTarget = target.asSpreader(Object[].class, target.type().parameterCount());
+ aCleanup = aCleanup.asSpreader(Object[].class, tpSize);
+
+ return MethodHandleImpl.makeTryFinally(aTarget, aCleanup, rtype, targetParamTypes);
+ }
+
+ /**
+ * Adapts a target method handle by pre-processing some of its arguments, starting at a given position, and then
+ * calling the target with the result of the pre-processing, inserted into the original sequence of arguments just
+ * before the folded arguments.
+ *
+ * This method is closely related to {@link #foldArguments(MethodHandle, MethodHandle)}, but allows to control the
+ * position in the parameter list at which folding takes place. The argument controlling this, {@code pos}, is a
+ * zero-based index. The aforementioned method {@link #foldArguments(MethodHandle, MethodHandle)} assumes position
+ * 0.
+ *
{@code
+ * // there are N arguments in A...
+ * T target(Z..., V, A[N]..., B...);
+ * V combiner(A...);
+ * T adapter(Z... z, A... a, B... b) {
+ * V v = combiner(a...);
+ * return target(z..., v, a..., b...);
+ * }
+ * // and if the combiner has a void return:
+ * T target2(Z..., A[N]..., B...);
+ * void combiner2(A...);
+ * T adapter2(Z... z, A... a, B... b) {
+ * combiner2(a...);
+ * return target2(z..., a..., b...);
+ * }
+ * }