invokedynamic call site, as reified to the bootstrap method.
- * Every instance of a call site corresponds to a distinct instance
- * of the invokedynamic instruction.
- * Call sites have state, one reference word, called the target,
- * and typed as a {@link MethodHandle}. When this state is null (as it is
- * initially) the call site is in the unlinked state. Otherwise, it is said
- * to be linked to its target.
+ * An {@code invokedynamic} call site, as reified by the
+ * containing class's bootstrap method.
+ * Every call site object corresponds to a distinct instance
+ * of the invokedynamic instruction, and vice versa.
+ * Every call site has one state variable, called the {@code target}.
+ * It is typed as a {@link MethodHandle}. This state is never null, and
+ * it is the responsibility of the bootstrap method to produce call sites
+ * which have been pre-linked to an initial target method.
* - * When an unlinked call site is executed, a bootstrap routine is called - * to finish the execution of the call site, and optionally to link - * the call site. + * (Note: The bootstrap method may elect to produce call sites of a + * language-specific subclass of {@code CallSite}. In such a case, + * the subclass may claim responsibility for initializing its target to + * a non-null value, by overriding {@link #initialTarget}.) *
+ * An {@code invokedynamic} instruction which has not yet been executed + * is said to be unlinked. When an unlinked call site is executed, + * the containing class's bootstrap method is called to manufacture a call site, + * for the instruction. If the bootstrap method does not assign a non-null + * value to the new call site's target variable, the method {@link #initialTarget} + * is called to produce the new call site's first target method. + *
+ * @see Linkage#registerBootstrapMethod(java.lang.Class, java.dyn.MethodHandle) * @author John Rose, JSR 292 EG */ public class CallSite { @@ -52,6 +62,15 @@ public class CallSite { final String name; final MethodType type; + /** + * Make a call site given the parameters from a call to the bootstrap method. + * The resulting call site is in an unlinked state, which means that before + * it is returned from a bootstrap method call it must be provided with + * a target method via a call to {@link CallSite#setTarget}. + * @param caller the class in which the relevant {@code invokedynamic} instruction occurs + * @param name the name specified by the {@code invokedynamic} instruction + * @param type the method handle type derived from descriptor of the {@code invokedynamic} instruction + */ public CallSite(Object caller, String name, MethodType type) { this.caller = caller; this.name = name; @@ -73,7 +92,9 @@ public class CallSite { *
* If the bootstrap method itself does not initialize the call site, * this method must be overridden, because it just raises an - * {@code InvokeDynamicBootstrapError}. + * {@code InvokeDynamicBootstrapError}, which in turn causes the + * linkage of the {@code invokedynamic} instruction to terminate + * abnormally. */ protected MethodHandle initialTarget() { throw new InvokeDynamicBootstrapError("target must be initialized before call site is linked: "+this); @@ -81,7 +102,7 @@ public class CallSite { /** * Report the current linkage state of the call site. (This is mutable.) - * The value is null if and only if the call site is currently unlinked. + * The value maybe null only if the call site is currently unlinked. * When a linked call site is invoked, the target method is used directly. * When an unlinked call site is invoked, its bootstrap method receives * the call, as if via {@link Linkage#bootstrapInvokeDynamic}. @@ -113,8 +134,9 @@ public class CallSite { * into the bootstrap method and/or the target methods used * at any given call site. * @param target the new target, or null if it is to be unlinked - * @throws WrongMethodTypeException if the new target is not null - * and has a method type that differs from the call site's {@link #type} + * @throws NullPointerException if the proposed new target is null + * @throws WrongMethodTypeException if the proposed new target + * has a method type that differs from the call site's {@link #type()} */ public void setTarget(MethodHandle target) { checkTarget(target); @@ -122,6 +144,7 @@ public class CallSite { } protected void checkTarget(MethodHandle target) { + target.type(); // provoke NPE if (!canSetTarget(target)) throw new WrongMethodTypeException(String.valueOf(target)); } @@ -132,7 +155,7 @@ public class CallSite { /** * Report the class containing the call site. - * This is immutable static context. + * This is an immutable property of the call site, set from the first argument to the constructor. * @return class containing the call site */ public Class callerClass() { @@ -141,7 +164,7 @@ public class CallSite { /** * Report the method name specified in the {@code invokedynamic} instruction. - * This is immutable static context. + * This is an immutable property of the call site, set from the second argument to the constructor. *
* Note that the name is a JVM bytecode name, and as such can be any * non-empty string, as long as it does not contain certain "dangerous" @@ -187,7 +210,7 @@ public class CallSite { * which are derived from its bytecode-level invocation descriptor. * The types are packaged into a {@link MethodType}. * Any linked target of this call site must be exactly this method type. - * This is immutable static context. + * This is an immutable property of the call site, set from the third argument to the constructor. * @return method type specified by the call site */ public MethodType type() { diff --git a/src/share/classes/java/dyn/InvokeDynamic.java b/src/share/classes/java/dyn/InvokeDynamic.java index 446c2d0c55bb7e27cdd07bdb949ae6c0708d31c3..2bec7b7dfe6a115c24086f052ad4c3a53eac16a4 100644 --- a/src/share/classes/java/dyn/InvokeDynamic.java +++ b/src/share/classes/java/dyn/InvokeDynamic.java @@ -26,10 +26,25 @@ package java.dyn; /** - * Syntactic marker interface to request javac to emit an {@code invokedynamic} instruction. + * Syntactic marker to request javac to emit an {@code invokedynamic} instruction. + * An {@code invokedynamic} instruction is a 5-byte bytecoded instruction + * which begins with an opcode byte of value 186 ({@code 0xBA}), + * and is followed by a two-byte index of a {@code NameAndType} constant + * pool entry, then by two zero bytes. The constant pool reference gives + * the method name and argument and return types of the call site; there + * is no other information provided at the call site. *
- * This type has no particular meaning as a class or interface supertype, and can never be instantiated. + * The {@code invokedynamic} instruction is incomplete without a target method. + * The target method is a property of the reified call site object + * (of type {@link CallSite}) which is in a one-to-one association with each + * corresponding {@code invokedynamic} instruction. The call site object + * is initially produced by a bootstrap method associated with + * the call site, via the various overloadings of {@link Linkage#registerBootstrapMethod}. + *
+ * The type {@code InvokeDynamic} has no particular meaning as a + * class or interface supertype, or an object type; it can never be instantiated. * Logically, it denotes a source of all dynamically typed methods. + * It may be viewed as a pure syntactic marker (an importable one) of static calls. * @author John Rose, JSR 292 EG */ public final class InvokeDynamic { diff --git a/src/share/classes/java/dyn/Linkage.java b/src/share/classes/java/dyn/Linkage.java index 09e84d16ac9355054a76c2690808db902ed6b3ed..cbeeb3351deb62695758f16e625f7f54c73e8c21 100644 --- a/src/share/classes/java/dyn/Linkage.java +++ b/src/share/classes/java/dyn/Linkage.java @@ -37,16 +37,19 @@ public class Linkage { private Linkage() {} // do not instantiate /** - * Register a bootstrap method for use for a given caller class. - * The method handle must be of a type equivalent to {@link Linkage#makeCallSite}. + * PROVISIONAL API, WORK IN PROGRESS: + * Register a bootstrap method to use when linking a given caller class. + * It must be a method handle of a type equivalent to {@link CallSite#CallSite}. + * In other words, it must act as a factory method which accepts the arguments + * to {@code CallSite}'s constructor (a class, a string, and a method type), + * and returns a {@code CallSite} object (possibly of a subclass of {@code CallSite}). *
- * The operation will fail with an exception if any of the following conditions hold: + * The registration will fail with an {@code IllegalStateException} if any of the following conditions hold: *
invokedynamic call sites everywhere.
*
* When this method returns, every invokedynamic instruction
@@ -163,6 +172,7 @@ public class Linkage {
}
/**
+ * PROVISIONAL API, WORK IN PROGRESS:
* Invalidate all invokedynamic call sites associated
* with the given class.
* (These are exactly those sites which report the given class
diff --git a/src/share/classes/java/dyn/MethodHandles.java b/src/share/classes/java/dyn/MethodHandles.java
index e7a6febb2c7e84fec94823e1d4dbc1514a6e6230..3a9f7ed3e972eb106955f7a30529f279f7bad591 100644
--- a/src/share/classes/java/dyn/MethodHandles.java
+++ b/src/share/classes/java/dyn/MethodHandles.java
@@ -73,6 +73,7 @@ public class MethodHandles {
}
/**
+ * PROVISIONAL API, WORK IN PROGRESS:
* A factory object for creating method handles, when the creation
* requires access checking. Method handles do not perform
* access checks when they are called; this is a major difference
@@ -108,8 +109,10 @@ public class MethodHandles {
* access. In any of these cases, an exception will be
* thrown from the attempted lookup.
* In general, the conditions under which a method handle may be
- * created for a method M are exactly as restrictive as the conditions
- * under which the lookup class could have compiled a call to M.
+ * created for a method {@code M} are exactly as restrictive as the conditions
+ * under which the lookup class could have compiled a call to {@code M}.
+ * At least some of these error conditions are likely to be
+ * represented by checked exceptions in the final version of this API.
*/
public static final
class Lookup {
@@ -142,27 +145,30 @@ public class MethodHandles {
this.lookupClass = lookupClass;
}
+ private static final Class PUBLIC_ONLY = sun.dyn.empty.Empty.class;
+
/** Version of lookup which is trusted minimally.
* It can only be used to create method handles to
* publicly accessible members.
*/
- public static final Lookup PUBLIC_LOOKUP = new Lookup(null);
+ public static final Lookup PUBLIC_LOOKUP = new Lookup(PUBLIC_ONLY);
/** Package-private version of lookup which is trusted. */
- static final Lookup IMPL_LOOKUP = new Lookup(Access.class);
+ static final Lookup IMPL_LOOKUP = new Lookup(null);
static { MethodHandleImpl.initLookup(IMPL_TOKEN, IMPL_LOOKUP); }
private static void checkUnprivilegedlookupClass(Class lookupClass) {
- if (lookupClass == null ||
- lookupClass == Access.class ||
- lookupClass.getName().startsWith("java.dyn."))
+ String name = lookupClass.getName();
+ if (name.startsWith("java.dyn.") || name.startsWith("sun.dyn."))
throw newIllegalArgumentException("illegal lookupClass: "+lookupClass);
}
@Override
public String toString() {
- if (lookupClass == null)
+ if (lookupClass == PUBLIC_ONLY)
return "public";
+ if (lookupClass == null)
+ return "privileged";
return lookupClass.getName();
}
@@ -202,6 +208,13 @@ public class MethodHandles {
* with the receiver type ({@code defc}) prepended.
* The method and all its argument types must be accessible to the lookup class.
*
+ * (BUG NOTE: The type {@code Object} may be prepended instead + * of the receiver type, if the receiver type is not on the boot class path. + * This is due to a temporary JVM limitation, in which MethodHandle + * claims to be unable to access such classes. To work around this + * bug, use {@code convertArguments} to normalize the type of the leading + * argument to a type on the boot class path, such as {@code Object}.) + *
* When called, the handle will treat the first argument as a receiver * and dispatch on the receiver's type to determine which method * implementation to enter. @@ -222,11 +235,11 @@ public class MethodHandles { /** * Produce an early-bound method handle for a virtual method, - * or a handle for a constructor, as if called from an {@code invokespecial} + * as if called from an {@code invokespecial} * instruction from {@code caller}. - * The type of the method handle will be that of the method or constructor, + * The type of the method handle will be that of the method, * with a suitably restricted receiver type (such as {@code caller}) prepended. - * The method or constructor and all its argument types must be accessible + * The method and all its argument types must be accessible * to the caller. *
* When called, the handle will treat the first argument as a receiver,
@@ -250,8 +263,7 @@ public class MethodHandles {
MemberName method = IMPL_NAMES.resolveOrFail(new MemberName(defc, name, type), false, specialCaller);
checkStatic(false, method, lookupClass);
if (name.equals("