com.oracle.truffle.api.dsl

Annotation Type Cached

@Retention(value=CLASS)
 @Target(value=PARAMETER)
public @interface Cached

A parameter annotated with Cached in a Specialization refers to a cached value of a specialization instance. A cached parameter value is initialized once using the initializer expression at specialization instantiation. For each call of the specialization method the cached value is provided by using the annotated parameter from the method body. Cache initializers are potentially executed before guard expressions declared in Specialization.guards().

A typical specialization may define multiple dynamic and multiple cached parameters. Dynamic parameter values are typically provided by executing child nodes of the operation. Cached parameters are initialized and stored once per specialization instantiation. Cached parameters are always constant at compile time. You may verify this by invoking CompilerAsserts.compilationConstant(Object) on any cached parameter. For consistency between specialization declarations cached parameters must be declared last in a specialization method.

The initializer expression of a cached parameter is defined using a subset of Java. This subset includes field/parameter accesses, function calls, type exact infix comparisons (==, !=, <, <=, >, >=), logical negation (!), logical disjunction (||), null, true, false, and integer literals. The return type of the initializer expression must be assignable to the parameter type. If the annotated parameter type is derived from Node then the Node instance is allowed to use the Node.replace(Node) method to replace itself. Bound elements without receivers are resolved using the following order:

1. Dynamic and cached parameters of the enclosing specialization.
2. Fields defined using NodeField for the enclosing node.
3. Public constructors of the type of the annotated parameter using the new keyword as method name.
4. Public and static methods or fields of the type of the annotated parameter.
5. Non-private, static or virtual methods or fields of enclosing node.
6. Non-private, static or virtual methods or fields of super types of the enclosing node.
7. Public and static methods or fields imported using ImportStatic.

The following examples explain the intended use of the Cached annotation. All of the examples have to be enclosed in the following node declaration:

 @NodeChild("operand")
 abstract TestNode extends Node {
   abstract void execute(Object operandValue);
   // ... example here ...
 }
 

1. This example defines one dynamic and one cached parameter. The operand parameter is representing the dynamic value of the operand while the cachedOperand is initialized once at first execution of the specialization (specialization instantiation time).

     @Specialization
     void doCached(int operand,  @Cached("operand") int cachedOperand) {
         CompilerAsserts.compilationConstant(cachedOperand);
         ...
     }
   
     Example executions:
     execute(1) => doCached(1, 1) // new instantiation, localOperand is bound to 1
     execute(0) => doCached(0, 1)
     execute(2) => doCached(2, 1)
   
    

2. We extend the previous example by a guard for the cachedOperand value to be equal to the dynamic operand value. This specifies that the specialization is instantiated for each individual operand value that is provided. There are a lot of individual int values and for each individual int value a new specialization would get instantiated. The Specialization.limit() property defines a limit for the number of specializations that can get instantiated. If the specialization instantiation limit is reached then no further specializations are instantiated. Like for other specializations if there are no more specializations defined an UnsupportedSpecializationException is thrown. The default specialization instantiation limit is 3.

    @Specialization(guards = "operand == cachedOperand")
    void doCached(int operand,  @Cached("operand") int cachedOperand) {
       CompilerAsserts.compilationConstant(cachedOperand);
       ...
    }
   
    Example executions:
    execute(0) => doCached(0, 0) // new instantiation, cachedOperand is bound to 0
    execute(1) => doCached(1, 1) // new instantiation, cachedOperand is bound to 1
    execute(1) => doCached(1, 1)
    execute(2) => doCached(2, 2) // new instantiation, cachedOperand is bound to 2
    execute(3) => throws UnsupportedSpecializationException // instantiation limit overflows
   
    

3. To handle the limit overflow we extend our example by an additional specialization named doNormal. This specialization has the same type restrictions but does not have local state nor the operand identity guard. It is also declared after doCached therefore it is only instantiated if the limit of the doCached specialization has been reached. In other words doNormal is more generic than doCached . The doNormal specialization uses replaces="doCached" to specify that all instantiations of doCached get removed if doNormal is instantiated. Alternatively if the replaces relation is omitted then all doCached instances remain but no new instances are created.

    @Specialization(guards = "operand == cachedOperand")
    void doCached(int operand,  @Cached("operand") int cachedOperand) {
       CompilerAsserts.compilationConstant(cachedOperand);
       ...
    }
   
    @Specialization(replaces = "doCached")
    void doNormal(int operand) {...}
   
    Example executions with replaces = "doCached":
    execute(0) => doCached(0, 0) // new instantiation, cachedOperand is bound to 0
    execute(1) => doCached(1, 1) // new instantiation, cachedOperand is bound to 1
    execute(1) => doCached(1, 1)
    execute(2) => doCached(2, 2) // new instantiation, cachedOperand is bound to 2
    execute(3) => doNormal(3)    // new instantiation of doNormal due to limit overflow; doCached gets removed.
    execute(1) => doNormal(1)
   
    Example executions without replaces = "doCached":
    execute(0) => doCached(0, 0) // new instantiation, cachedOperand is bound to 0
    execute(1) => doCached(1, 1) // new instantiation, cachedOperand is bound to 1
    execute(1) => doCached(1, 1)
    execute(2) => doCached(2, 2) // new instantiation, cachedOperand is bound to 2
    execute(3) => doNormal(3)    // new instantiation of doNormal due to limit overflow
    execute(1) => doCached(1, 1)
   
    

4. This next example shows how methods from the enclosing node can be used to initialize cached parameters. Please note that the visibility of transformLocal must not be private.

    @Specialization
    void s(int operand,  @Cached("transformLocal(operand)") int cachedOperand) {
    }
   
    int transformLocal(int operand) {
        return operand & 0x42;
    }
   
    

5. The new keyword can be used to initialize a cached parameter using a constructor of the parameter type.

    @Specialization
    void s(Object operand,  @Cached("new()") OtherNode someNode) {
        someNode.execute(operand);
    }
   
    static class OtherNode extends Node {
   
        public String execute(Object value) {
            throw new UnsupportedOperationException();
        }
    }
   
    

6. Java types without public constructor but with a static factory methods can be initialized by just referencing its static factory method and its parameters. In this case BranchProfile.create() is used to instantiate the BranchProfile instance.

    @Specialization
    void s(int operand,  @Cached("create()") BranchProfile profile) {
    }
    

Since:

0.8 or earlier

See Also:

Specialization.guards(), Specialization.replaces(), Specialization.limit(), ImportStatic, @CachedContext to access the current context., @CachedLanguage to access the current Truffle language.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	adopt Specifies whether the cached parameter values of type NodeInterface should be adopted as its child by the current node.
boolean	allowUncached Allows the Cached.value() to be used for Cached.uncached().
int	dimensions Specifies the number of array dimensions to be marked as compilation final.
String[]	parameters Specifies the bindings used for the $parameters variable in cached or uncached initializers.
String	uncached Defines the initializer that is used for uncached nodes or uncached versions of exported library messages.
String	value Defines the initializer expression of the cached parameter value.
boolean	weak If set to true then weak references will be used to refer to this cached value in the generated node.

Element Detail

value

public abstract String value

Defines the initializer expression of the cached parameter value.

Since:

0.8 or earlier

See Also:

Cached

Default:

"create($parameters)"

uncached

public abstract String uncached

Defines the initializer that is used for uncached nodes or uncached versions of exported library messages.

Since:

19.0

See Also:

GenerateUncached

Default:

"getUncached($parameters)"

dimensions

public abstract int dimensions

Specifies the number of array dimensions to be marked as compilation final. This value must be specified for all array-typed cached values except node arrays and must be left unspecified in other cases where it has no meaning. The allowed range is from 0 to the number of declared array dimensions (inclusive). Specifically, a dimensions value of 0 marks only the reference to the (outermost) array as final but not its elements, a value of 1 marks the outermost array and all its elements as final but not the elements of any nested arrays. If not specified and the cached value type is an array type then this will cause a warning and in later releases an error.

Since:

0.26

See Also:

CompilerDirectives.CompilationFinal.dimensions()

Default:

-1

allowUncached

public abstract boolean allowUncached

Allows the Cached.value() to be used for Cached.uncached(). This is useful if the expression is the same for Cached.value() and Cached.uncached(). By setting Cached.allowUncached() to true it is not necessary to repeat the Cached.value() expression in the Cached.uncached() expression. This flag cannot be set in combination with Cached.uncached().

Since:

19.0

Default:

false

parameters

public abstract String[] parameters

Specifies the bindings used for the $parameters variable in cached or uncached initializers.

Since:

19.0

Default:

{}

weak

public abstract boolean weak

If set to true then weak references will be used to refer to this cached value in the generated node. The default value is false. The weak cached parameter is guaranteed to not become null in guards or specialization method invocations. If a weak cached parameter gets collected by the GC, then any compiled code remain unaffected and the specialization instance will not be removed. Specializations with collected cached references continue to count to the specialization limit. This is necessary to provide an upper bound for the number of invalidations that may happen for this specialization.

A weak cached parameter implicitly adds a weakRef.get() != null guard that is invoked before the cached value is referenced for the first time. This means that specializations which previously did not result in fall-through behavior may now fall-through. This is important if used in combination with Fallback. Weak cached parameters that are used as part of uncached nodes, execute the cached initializer for each execution and therefore implicitly do not use a weak reference.

Example usage:

 @GenerateUncached
 abstract class WeakInlineCacheNode extends Node {

     abstract Object execute(Object arg0);

     @Specialization(guards = "cachedArg.equals(arg)", limit = "3")
     Object s0(String arg,
                     @Cached(value = "arg", weak = true) String cachedArg) {
         assertNotNull(cachedStorage);
         return arg;
     }
 }
 

Since:

20.2

See Also:

TruffleWeakReference

Default:

false

adopt

public abstract boolean adopt

Specifies whether the cached parameter values of type NodeInterface should be adopted as its child by the current node. The default value is true, therefore all cached values of type NodeInterface and arrays of the same type are adopted. If the value is set to false, then no adoption is performed. It is useful to set adopt to false when nodes need to be referenced more than once in the AST.

If the type of the field is an NodeInterface array and adopt is set to false, then the compilation final dimensions attribute needs to be specified explicitly.

Since:

20.2

Default:

true