- * 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(); -}