com.oracle.truffle.api.library

Annotation Type CachedLibrary

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

The cached library annotation allows to use Truffle Libraries conveniently in specializations or exported messages. It is designed as the primary way of using libraries. The CachedLibrary annotation may be used for any parameters of methods annotated with @Specialization or @ExportMessage.

Using Specialized Libraries

A cached library can be specialized for a value that is referred to with the value expression attribute. A specialized library implicitly prepends a guard for the acceptance of a library with the provided value expression. Adding the acceptance guard leads to multiple specialization instances as it binds to the cached library value. The specialization or export limit attribute must therefore be specified. If this limit overflows then the operation will rewrite itself to an uncached version of the library. Multiple specialized libraries may be used per export or specialization. The acceptance guards for these libraries will be added in the order of their declaration.

Usage:

 @NodeChild
 @NodeChild
 abstract static class ArrayReadNode extends ExpressionNode {
     @Specialization(guards = "arrays.isArray(array)", limit = "2")
     int doDefault(Object array, int index,
                     @CachedLibrary("array") ArrayLibrary arrays) {
         return arrays.read(array, index);
     }
 }
 

It is recommended to use the plural of the specialized parameter name as naming convention for the library parameter name, e.g. a library for an array value is called arrays. If multiple libraries are specialized for the same specialized expression it is recommended to prepend the library name e.g. interopArrays.

Using Dispatched Libraries

If no specialized value expression can be specified, i.e. if the value is computed as part of the operation, then a dispatched version of a library can be used by omitting the value attribute and specifying the CachedLibrary.limit() attribute instead. A dispatched library builds the specialized value inline cache internally for each invocation of a message instead of once per outer specialization or export. An instance of a dispatched library therefore accepts any value as receiver. It is recommended to use the same generic library instance for few message invocations of similar values only, could lead to duplication of inline cache dispatches in the compiled code. The limit of a dispatched library may be set to 0 to directly switch to an uncached version of a library.

Usage:

The following example combines the use of specialized and dispatched libraries. In this example the array is read twice. For the first outer read the specializing expression can be used. For the second read the specializing expression cannot be used as it depends on the result of the outer read. We therefore use a dispatched library for the inner array.

 @NodeChild
 @NodeChild
 @NodeChild
 abstract static class TwoDimReadNode extends ExpressionNode {
     @Specialization(guards = "outerArrays.isArray(array)", limit = "2")
     int doDefault(Object array, int outerIndex, int innerIndex,
                     @CachedLibrary("array") ArrayLibrary outerArrays,
                     @CachedLibrary(limit = "2") ArrayLibrary innerArrays) {
         return innerArrays.read(outerArrays.read(outerIndex), innerIndex);
     }
 }
 

Since:

19.0

See Also:

for manually instantiating libraries, Truffle Library reference documentation

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	limit Sets the limit expression when using dispatched libraries.
String	value Sets the specialized value expression when using specialized libraries.

Element Detail

value

public abstract String value

Sets the specialized value expression when using specialized libraries. The same syntax applies as for Cached value expressions.

Since:

19.0

See Also:

for usage examples.

Default:

""

limit

public abstract String limit

Sets the limit expression when using dispatched libraries. The limit expression sets the number of internally dispatched specialized libraries until an uncached version of the library will be used.

Since:

19.0

See Also:

for usage examples.

Default:

""