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