@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 documentation
public abstract String value
Cached
value expressions.for usage examples.
public abstract String limit
uncached
version of the library will be used.for usage examples.