* A call site is initially created in an unlinked state, * which is distinguished by a null target variable. * Before the call site may be invoked (and before certain other * operations are attempted), the call site must be linked to * a non-null target. *
* A call site may be relinked by changing its target. * The new target must be non-null and must have the same * {@linkplain MethodHandle#type() type} * as the previous target. * Thus, though a call site can be relinked to a series of * successive targets, it cannot change its type. *
* Linkage happens once in the lifetime of any given {@code CallSite} object. * Because of call site invalidation, this linkage can be repeated for * a single {@code invokedynamic} instruction, with multiple {@code CallSite} objects. * When a {@code CallSite} is unlinked from an {@code invokedynamic} instruction, * the instruction is reset so that it is no longer associated with * the {@code CallSite} object, but the {@code CallSite} does not change * state. *
* Here is a sample use of call sites and bootstrap methods which links every * dynamic call site to print its arguments:
@BootstrapMethod(value=PrintArgsDemo.class, name="bootstrapDynamic")
static void test() throws Throwable {
InvokeDynamic.baz("baz arg", 2, 3.14);
}
private static void printArgs(Object... args) {
System.out.println(java.util.Arrays.deepToString(args));
}
private static final MethodHandle printArgs;
static {
MethodHandles.Lookup lookup = MethodHandles.lookup();
Class thisClass = lookup.lookupClass(); // (who am I?)
printArgs = lookup.findStatic(thisClass,
"printArgs", MethodType.methodType(void.class, Object[].class));
}
private static CallSite bootstrapDynamic(Class caller, String name, MethodType type) {
// ignore caller and name, but match the type:
return new CallSite(MethodHandles.collectArguments(printArgs, type));
}
* The arguments are the same as those passed to the bootstrap method. * Thus, a bootstrap method is free to ignore the arguments and simply * create a "blank" {@code CallSite} object of an appropriate subclass. *
* If the bootstrap method itself does not initialize the call site, * this method must be overridden, because it just raises an * {@code InvokeDynamicBootstrapError}, which in turn causes the * linkage of the {@code invokedynamic} instruction to terminate * abnormally. * @deprecated transitional form defined in EDR but removed in PFD */ protected MethodHandle initialTarget(Class callerClass, String name, MethodType type) { throw new InvokeDynamicBootstrapError("target must be initialized before call site is linked: "+name+type); } /** * Report the current linkage state of the call site. (This is mutable.) * The value may not be null after the {@code CallSite} object is returned * from the bootstrap method of the {@code invokedynamic} instruction. * When an {@code invokedynamic} instruction is executed, the target method * of its associated {@code call site} object is invoked directly, * as if via {@link MethodHandle}{@code .invoke}. *
* The interactions of {@code getTarget} with memory are the same * as of a read from an ordinary variable, such as an array element or a * non-volatile, non-final field. *
* In particular, the current thread may choose to reuse the result * of a previous read of the target from memory, and may fail to see * a recent update to the target by another thread. * @return the current linkage state of the call site * @see #setTarget */ public MethodHandle getTarget() { return target; } /** * Set the target method of this call site. *
* The interactions of {@code setTarget} with memory are the same * as of a write to an ordinary variable, such as an array element or a * non-volatile, non-final field. *
* In particular, unrelated threads may fail to see the updated target * until they perform a read from memory. * Stronger guarantees can be created by putting appropriate operations * into the bootstrap method and/or the target methods used * at any given call site. * @param newTarget the new target * @throws NullPointerException if the proposed new target is null * @throws WrongMethodTypeException if the call site is linked and the proposed new target * has a method type that differs from the previous target */ public void setTarget(MethodHandle newTarget) { MethodType newType = newTarget.type(); // null check! MethodHandle oldTarget = this.target; if (oldTarget == null) { // CallSite is not yet linked. assert(!isLinked()); this.target = newTarget; // might be null! return; } MethodType oldType = oldTarget.type(); if (!newTarget.type().equals(oldType)) throw wrongTargetType(newTarget, oldType); if (oldTarget != newTarget) CallSiteImpl.setCallSiteTarget(IMPL_TOKEN, this, newTarget); } private static WrongMethodTypeException wrongTargetType(MethodHandle target, MethodType type) { return new WrongMethodTypeException(String.valueOf(target)+target.type()+" should be of type "+type); } /** Produce a printed representation that displays information about this call site * that may be useful to the human reader. */ @Override public String toString() { return "CallSite"+(target == null ? "" : target.type()); } /** * PROVISIONAL API, WORK IN PROGRESS: * Produce a method handle equivalent to an invokedynamic instruction * which has been linked to this call site. *
If this call site is a {@link ConstantCallSite}, this method * simply returns the call site's target, since that will not change. *
Otherwise, this method is equivalent to the following code: *
* MethodHandle getTarget, invoker, result;
* getTarget = MethodHandles.lookup().bind(this, "getTarget", MethodType.methodType(MethodHandle.class));
* invoker = MethodHandles.exactInvoker(this.type());
* result = MethodHandles.foldArguments(invoker, getTarget)
*