* {@code CallSite} is an abstract class which does not allow * direct subclassing by users. It has three immediate, * concrete subclasses that may be either instantiated or subclassed. *
* A non-constant call site may be relinked by changing its target. * The new target 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. *
* Here is a sample use of call sites and bootstrap methods which links every * dynamic call site to print its arguments:
static void test() throws Throwable {
// THE FOLLOWING LINE IS PSEUDOCODE FOR A JVM INSTRUCTION
InvokeDynamic[#bootstrapDynamic].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(MethodHandles.Lookup caller, String name, MethodType type) {
// ignore caller and name, but match the type:
return new ConstantCallSite(MethodHandles.collectArguments(printArgs, type));
}
* Before this {@code CallSite} object is returned from a bootstrap method, * it is usually provided with a more useful target method, * via a call to {@link CallSite#setTarget(MethodHandle) setTarget}. * @throws NullPointerException if the proposed type is null */ /*package-private*/ CallSite(MethodType type) { target = MethodHandles.invokers(type).uninitializedCallSite(); } /** * Make a blank call site object, possibly equipped with an initial target method handle. * @param target the method handle which will be the initial target of the call site * @throws NullPointerException if the proposed target is null */ /*package-private*/ CallSite(MethodHandle target) { target.type(); // null check this.target = target; } /** * Report the type of this call site's target. * Although targets may change, the call site's type can never change. * The {@code setTarget} method enforces this invariant by refusing any new target that does * not have the previous target's type. * @return the type of the current target, which is also the type of any future target */ public MethodType type() { return target.type(); } /** Called from JVM (or low-level Java code) after the BSM returns the newly created CallSite. * The parameters are JVM-specific. */ void initializeFromJVM(String name, MethodType type, MemberName callerMethod, int callerBCI) { if (this.vmmethod != null) { // FIXME throw new InvokeDynamicBootstrapError("call site has already been linked to an invokedynamic instruction"); } if (!this.type().equals(type)) { throw wrongTargetType(target, type); } this.vmindex = callerBCI; this.vmmethod = callerMethod; } /** * Report the current linkage state of the call site, a value which may change over time. *
* If a {@code CallSite} object is returned * from the bootstrap method of the {@code invokedynamic} instruction, * the {@code CallSite} is permanently bound to that instruction. * When the {@code invokedynamic} instruction is executed, the target method * of its associated call site object is invoked directly. * It is as if the instruction calls {@code getTarget} and then * calls {@link MethodHandle#invokeExact invokeExact} on the result. *
* Unless specified differently by a subclass, * 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. *
* In a {@linkplain ConstantCallSite constant call site}, the {@code getTarget} method behaves * like a read from a {@code final} field of the {@code CallSite}. *
* In a {@linkplain VolatileCallSite volatile call site}, the {@code getTarget} method behaves * like a read from a {@code volatile} field of the {@code CallSite}. *
* This method may not be overridden by application code. * @return the current linkage state of the call site, its target method handle * @see ConstantCallSite * @see VolatileCallSite * @see #setTarget */ public final MethodHandle getTarget() { return getTarget0(); } /** * Privileged implementations can override this to force final or volatile semantics on getTarget. */ /*package-private*/ MethodHandle getTarget0() { return target; } /** * Set the target method of this call site. *
* Unless a subclass of CallSite documents otherwise, * 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 proposed new target * has a method type that differs from the previous target * @throws UnsupportedOperationException if the call site is * in fact a {@link ConstantCallSite} */ public void setTarget(MethodHandle newTarget) { checkTargetChange(this.target, newTarget); setTargetNormal(newTarget); } void checkTargetChange(MethodHandle oldTarget, MethodHandle newTarget) { MethodType oldType = oldTarget.type(); MethodType newType = newTarget.type(); // null check! if (!newType.equals(oldType)) throw wrongTargetType(newTarget, oldType); } private static WrongMethodTypeException wrongTargetType(MethodHandle target, MethodType type) { return new WrongMethodTypeException(String.valueOf(target)+" should be of type "+type); } /** * Produce a method handle equivalent to an invokedynamic instruction * which has been linked to this call site. *
If this call site is a {@linkplain ConstantCallSite constant call site}, * this method simply returns the call site's target, since that will never 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)
*