public class MutableCallSite extends CallSite
CallSitewhose target variable behaves like an ordinary field. An
invokedynamicinstruction linked to a
MutableCallSitedelegates all calls to the site's current target. The dynamic invoker of a mutable call site also delegates each call to the site's current target.
Here is an example of a mutable call site which introduces a state variable into a method handle chain.
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.
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.)
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 volatile call site instead.
|Constructor and Description|
Creates a call site object with an initial target method handle.
Creates a blank call site object with the given method type.
|Modifier and Type||Method and Description|
Produces a method handle equivalent to an invokedynamic instruction which has been linked to this call site.
Returns the target method of the call site, which behaves like a normal field of the
Updates the target method of this call site, as a normal variable.
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.
public MutableCallSite(MethodType type)
The type of the call site is permanently set to the given type.
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
type- the method type that this call site will have
NullPointerException- if the proposed type is null
public MutableCallSite(MethodHandle target)
target- the method handle that will be the initial target of the call site
NullPointerException- if the proposed target is null
public final MethodHandle getTarget()
The interactions of
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.
public void setTarget(MethodHandle newTarget)
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.
public final MethodHandle dynamicInvoker()
This method is equivalent to the following code:
MethodHandle getTarget, invoker, result; getTarget = MethodHandles.publicLookup().bind(this, "getTarget", MethodType.methodType(MethodHandle.class)); invoker = MethodHandles.exactInvoker(this.type()); result = MethodHandles.foldArguments(invoker, getTarget)
public static void syncAll(MutableCallSite sites)
This operation does not reverse any calls that have already started on an old target value. (Java supports 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
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
should generally be performed under some sort of mutual exclusion.
Note that reader threads may observe an updated target as early
setTarget call that install the value
(and before the
syncAll that confirms the value).
On the other hand, reader threads may observe previous versions of
the target until the
syncAll call returns
(and after the
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.
sites contains a null element,
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
Vis created, and written by the current thread. As defined by the JMM, this write is a global synchronization event.
V. (In some implementations, this means that the current thread performs a global release operation.)
Sis taken to happen before the volatile write to
Vis placed (in an implementation specific manner) in the global synchronization order.
T(other than the current thread). If
Texecutes a synchronization action
Aafter the volatile write to
V(in the global synchronization order), it is therefore required to see either the current target of
S, or a later write to that target, if it executes a read on the target of
S. (This constraint is called "synchronization-order consistency".)
Vwill not be elided, even though its written value is indeterminate and its read value is not used.
Vwere performed by
Timmediately after its action
A. In the local ordering of actions in
T, this read happens before any future read of the target of
S. It is as if the implementation arbitrarily picked a read of
S's target by
T, and forced a read of
Vto precede it, thereby ensuring communication of the new target value.
As long as the constraints of the Java Memory Model are obeyed,
implementations may delay the completion of a
operation while other threads (
T above) continue to
use previous values of
However, implementations are (as always) encouraged to avoid
livelock, and to eventually require all threads to take account
of the updated target.
For performance reasons,
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.
Simple implementations of
MutableCallSite may use
a volatile variable for the target of a mutable call site.
In such an implementation, the
syncAll method can be a no-op,
and yet it will conform to the JMM behavior documented above.
sites- an array of call sites to be synchronized
NullPointerException- if the
sitesarray reference is null or the array contains a null
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2023, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.