Class ClassValue<T>
- Type Parameters:
T- the type of the associated value
Class object.
For example, if a dynamic language needs to construct a message dispatch
table for each class encountered at a message send call site,
it can use a ClassValue to cache information needed to
perform the message send quickly, for each class encountered.
The basic operation of a ClassValue is get, which
returns the associated value, initially created by an invocation to computeValue; multiple invocations may happen under race, but
exactly one value is associated to a Class and returned.
Another operation is remove: it clears the associated value
(if it exists), and ensures the next associated value is computed with input
states up-to-date with the removal.
For a particular association, there is a total order for accesses to the associated value. Accesses are atomic; they include:
- A read-only access by
get - An attempt to associate the return value of a
computeValuebyget - Clearing of an association by
remove
get call always include at least one access; a remove call
always has exactly one access; a computeValue call always happens
between two accesses. This establishes the order of computeValue
calls with respect to remove calls and determines whether the
results of a computeValue can be successfully associated by a
get.- Since:
- 1.7
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected abstract TcomputeValue(Class<?> type) Computes the value to associate to the givenClass.Returns the value associated to the givenClass.voidRemoves the associated value for the givenClassand invalidates all out-of-date computations.
-
Constructor Details
-
ClassValue
protected ClassValue()Sole constructor. (For invocation by subclass constructors, typically implicit.)
-
-
Method Details
-
computeValue
Computes the value to associate to the givenClass.This method is invoked when the initial read-only access by
getfinds no associated value.If this method throws an exception, the initiating
getcall will not attempt to associate a value, and may terminate by returning the associated value if it exists, or by propagating that exception otherwise.Otherwise, the value is computed and returned. An attempt to associate the return value happens, with one of the following outcomes:
- The associated value is present; it is returned and no association is done.
- The most recent
removecall, if it exists, does not happen-before (JLS 17.4.5) the finish of thecomputeValuethat computed the value to associate. A new invocation tocomputeValue, which thatremovecall happens-before, will re-establish this happens-before relationship. - Otherwise, this value is successfully associated and returned.
- API Note:
- A
computeValuecall may, due to class loading or other circumstances, recursively callgetorremovefor the sametype. The recursiveget, if the recursion stops, successfully finishes and this initiatinggetobserves the associated value from recursion. The recursiveremoveis no-op, since being on the same thread, theremovealready happens-before the finish of thiscomputeValue; the result from thiscomputeValuestill may be associated. - Parameters:
type- theClassto associate a value to- Returns:
- the newly computed value to associate
- See Also:
-
get
Returns the value associated to the givenClass.This method first performs a read-only access, and returns the associated value if it exists. Otherwise, this method tries to associate a value from a
computeValueinvocation until the associated value exists, which could be associated by a competing thread.This method may throw an exception from a
computeValueinvocation. In this case, no association happens.- Parameters:
type- theClassto retrieve the associated value for- Returns:
- the value associated to the given
Class - Throws:
NullPointerException- if the argument isnull- See Also:
-
remove
Removes the associated value for the givenClassand invalidates all out-of-date computations. If this association is subsequently accessed, this removal happens-before (JLS 17.4.5) the finish of thecomputeValuecall that returned the associated value.- Parameters:
type- the type whose class value must be removed- Throws:
NullPointerException- if the argument isnull
-