Package com.oracle.truffle.api.library

Annotation Interface CachedLibrary

@Retention(CLASS) @Target(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 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:

  • Optional Element Summary

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

  • Element Details

    • value

      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:
      Default:
      ""

    • limit

      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:
      Default:
      ""