Added in API level 34

ClassValue

abstract class ClassValue<T : Any!>
kotlin.Any
   ↳ java.lang.ClassValue

Lazily associate a computed value with any 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 computeValue by get
  • Clearing of an association by remove
A 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.

Summary

Protected constructors

Sole constructor.
Public methods
open T
get(type: Class<*>!)

{@return the value associated to the given {@code Class}}

open Unit
remove(type: Class<*>!)

Removes the associated value for the given Class and invalidates all out-of-date computations.
Protected methods
abstract T
computeValue(type: Class<*>!)

Computes the value to associate to the given Class.

Protected constructors

ClassValue

Added in API level 34
protected ClassValue()

Sole constructor. (For invocation by subclass constructors, typically implicit.)

Public methods

get

Added in API level 34
open fun get(type: Class<*>!): T

{@return the value associated to the given {@code Class}}

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 computeValue invocation until the associated value exists, which could be associated by a competing thread.

This method may throw an exception from a computeValue invocation. In this case, no association happens.

Parameters
type Class<*>!: the Class to retrieve the associated value for
Exceptions
java.lang.NullPointerException if the argument is null

remove

Added in API level 34
open fun remove(type: Class<*>!): Unit

Removes the associated value for the given Class and invalidates all out-of-date computations. If this association is subsequently accessed, this removal happens-before (JLS {@jls * 17.4.5}) the finish of the computeValue call that returned the associated value.

Parameters
type Class<*>!: the type whose class value must be removed
Exceptions
java.lang.NullPointerException if the argument is null

Protected methods

computeValue

Added in API level 34
protected abstract fun computeValue(type: Class<*>!): T

Computes the value to associate to the given Class.

This method is invoked when the initial read-only access by get finds no associated value.

If this method throws an exception, the initiating get call 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 remove call, if it exists, does not happen-before (JLS {@jls 17.4.5}) the finish of the computeValue that computed the value to associate. A new invocation to computeValue, which that remove call happens-before, will re-establish this happens-before relationship.
  • Otherwise, this value is successfully associated and returned.
Parameters
type Class<*>!: the Class to associate a value to
Return
T the newly computed value to associate

See Also