+ * 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.) + *
+ * The {@link #syncAll syncAll} operation provides a way to force threads + * to accept a new target value, even if there is no other synchronization. + *
+ * 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(); + } + + /** + * 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(); +}