@Retention(value=CLASS) @Target(value=PARAMETER) public @interface CachedLibrary
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.
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.
@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.
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.
@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);
}
}
for manually instantiating libraries,
Truffle Library reference documentationpublic abstract String value
Cached value expressions.for usage examples.public abstract String limit
uncached version of the library will be used.for usage examples.