* Here is an example of a mutable call site which introduces a * state variable into a method handle chain. * *
{@code
MutableCallSite name = new MutableCallSite(MethodType.methodType(String.class));
MethodHandle MH_name = name.dynamicInvoker();
MethodType MT_str1 = MethodType.methodType(String.class);
MethodHandle MH_upcase = MethodHandles.lookup()
.findVirtual(String.class, "toUpperCase", MT_str1);
MethodHandle worker1 = MethodHandles.filterReturnValue(MH_name, MH_upcase);
name.setTarget(MethodHandles.constant(String.class, "Rocky"));
assertEquals("ROCKY", (String) worker1.invokeExact());
name.setTarget(MethodHandles.constant(String.class, "Fred"));
assertEquals("FRED", (String) worker1.invokeExact());
// (mutation can be continued indefinitely)
* }* The same call site may be used in several places at once. *
{@code
MethodType MT_str2 = MethodType.methodType(String.class, String.class);
MethodHandle MH_cat = lookup().findVirtual(String.class,
"concat", methodType(String.class, String.class));
MethodHandle MH_dear = MethodHandles.insertArguments(MH_cat, 1, ", dear?");
MethodHandle worker2 = MethodHandles.filterReturnValue(MH_name, MH_dear);
assertEquals("Fred, dear?", (String) worker2.invokeExact());
name.setTarget(MethodHandles.constant(String.class, "Wilma"));
assertEquals("WILMA", (String) worker1.invokeExact());
assertEquals("Wilma, dear?", (String) worker2.invokeExact());
* }* Non-synchronization of target values: * A write to a mutable call site's target does not force other threads * to become aware of the updated value. Threads which do not perform * suitable synchronization actions relative to the updated call site * may cache the old target value and delay their use of the new target * value indefinitely. * (This is a normal consequence of the Java Memory Model as applied * to object fields.) *
* For target values which will be frequently updated, consider using * a {@linkplain VolatileCallSite volatile call site} instead. * @author John Rose, JSR 292 EG */ public class MutableCallSite extends CallSite { /** * Creates a blank call site object with the given method type. * The initial target is set to a method handle of the given type * which will throw an {@link IllegalStateException} if called. *
* The type of the call site is permanently set to the given type. *
* Before this {@code CallSite} object is returned from a bootstrap method, * or invoked in some other manner, * it is usually provided with a more useful target method, * via a call to {@link CallSite#setTarget(MethodHandle) setTarget}. * @param type the method type that this call site will have * @throws NullPointerException if the proposed type is null */ public MutableCallSite(MethodType type) { super(type); } /** * Creates a call site object with an initial target method handle. * The type of the call site is permanently set to the initial target's type. * @param target the method handle that will be the initial target of the call site * @throws NullPointerException if the proposed target is null */ public MutableCallSite(MethodHandle target) { super(target); } /** * Returns the target method of the call site, which behaves * like a normal field of the {@code MutableCallSite}. *
* 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 linkage state of this call site, a method handle which can change over time * @see #setTarget */ @Override public final MethodHandle getTarget() { return target; } /** * Updates the target method of this call site, as a normal variable. * The type of the new target must agree with the type of the old target. *
* The interactions 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 * @see #getTarget */ @Override public void setTarget(MethodHandle newTarget) { checkTargetChange(this.target, newTarget); setTargetNormal(newTarget); } /** * {@inheritDoc} */ @Override public final MethodHandle dynamicInvoker() { return makeDynamicInvoker(); } // Android-changed: not exposing incomplete implementation. // /** // * Performs a synchronization operation on each call site in the given array, // * forcing all other threads to throw away any cached values previously // * loaded from the target of any of the call sites. // *
// * This operation does not reverse any calls that have already started // * on an old target value. // * (Java supports {@linkplain java.lang.Object#wait() forward time travel} only.) // *
// * The overall effect is to force all future readers of each call site's target // * to accept the most recently stored value. // * ("Most recently" is reckoned relative to the {@code syncAll} itself.) // * Conversely, the {@code syncAll} call may block until all readers have // * (somehow) decached all previous versions of each call site's target. // *
// * To avoid race conditions, calls to {@code setTarget} and {@code syncAll} // * should generally be performed under some sort of mutual exclusion. // * Note that reader threads may observe an updated target as early // * as the {@code setTarget} call that install the value // * (and before the {@code syncAll} that confirms the value). // * On the other hand, reader threads may observe previous versions of // * the target until the {@code syncAll} call returns // * (and after the {@code setTarget} that attempts to convey the updated version). // *
// * This operation is likely to be expensive and should be used sparingly. // * If possible, it should be buffered for batch processing on sets of call sites. // *
// * If {@code sites} contains a null element, // * a {@code NullPointerException} will be raised. // * In this case, some non-null elements in the array may be // * processed before the method returns abnormally. // * Which elements these are (if any) is implementation-dependent. // * // *
// * The following effects are apparent, for each individual call site {@code S}: // *
// * As long as the constraints of the Java Memory Model are obeyed, // * implementations may delay the completion of a {@code syncAll} // * operation while other threads ({@code T} above) continue to // * use previous values of {@code S}'s target. // * However, implementations are (as always) encouraged to avoid // * livelock, and to eventually require all threads to take account // * of the updated target. // * // *
// * Discussion: // * For performance reasons, {@code syncAll} is not a virtual method // * on a single call site, but rather applies to a set of call sites. // * Some implementations may incur a large fixed overhead cost // * for processing one or more synchronization operations, // * but a small incremental cost for each additional call site. // * In any case, this operation is likely to be costly, since // * other threads may have to be somehow interrupted // * in order to make them notice the updated target value. // * However, it may be observed that a single call to synchronize // * several sites has the same formal effect as many calls, // * each on just one of the sites. // * // *
// * Implementation Note: // * Simple implementations of {@code MutableCallSite} may use // * a volatile variable for the target of a mutable call site. // * In such an implementation, the {@code syncAll} method can be a no-op, // * and yet it will conform to the JMM behavior documented above. // * // * @param sites an array of call sites to be synchronized // * @throws NullPointerException if the {@code sites} array reference is null // * or the array contains a null // */ // public static void syncAll(MutableCallSite[] sites) { // if (sites.length == 0) return; // STORE_BARRIER.lazySet(0); // for (int i = 0; i < sites.length; i++) { // sites[i].getClass(); // trigger NPE on first null // } // // FIXME: NYI // } // private static final AtomicInteger STORE_BARRIER = new AtomicInteger(); }