Annotation Interface Operation

@Retention(SOURCE) @Target(TYPE) public @interface Operation
Declares an operation. An operation serves as a specification for a bytecode instruction in the generated interpreter.

An operation class is declared the same way as a regular Truffle AST node. It declares a set of specializations that define the behaviour of the operation. The specializations should all have a specific number of operands (dynamic input parameters), and they should all be void or return a value. These properties make up the "signature" for an operation; for example, an operation may consume two input values and produce a value.

Operations have a few additional restrictions compared to Truffle AST nodes:

  • The operation class should be nested inside the bytecode root node class.
  • The operation class should be static final, and have at least package-private visibility.
  • The operation class should not extend/implement any other class/interface. (For convenient access to helper methods/fields from Truffle DSL expressions, consider using ImportStatic. Static imports can be declared on the root node or on individual operations; operation imports take precedence over root node imports.)
  • The operation class should not contain instance members.
  • The specializations also have some differences:
    • Specializations should be static and have at least package-private visibility. Members referenced in Truffle DSL expressions (e.g., @Cached parameters) have the same restrictions.
    • The parameters of any Fallback specialization must be of type Object. Unlike ASTs, which can define execute methods with specialized parameter types, operation arguments are consumed from the stack, where the type is not guaranteed.
    • Specializations can bind some special parameters: $rootNode, $bytecodeNode, and $bytecodeIndex.
To aid migration, there is also the OperationProxy annotation that creates an operation from an existing AST node. This proxy can be defined outside of the root node, which may be convenient for code organization.

Refer to the user guide for more details.

Since:
24.2

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    forceCached
    Whether executing this operation should force the uncached interpreter (if enabled) to transition to cached.
    String
    javadoc
    Optional documentation for the operation.
    Class<? extends Tag>[]
    tags
    The instrumentation tags that should be implicitly associated with this operation.

  • Element Details

    • forceCached

      boolean forceCached
      Whether executing this operation should force the uncached interpreter (if enabled) to transition to cached. This field allows you to generate an uncached interpreter with operations that cannot be easily rewritten to support uncached execution. It should only be set if the uncached interpreter is enabled.

      By default, to generate an uncached interpreter the Bytecode DSL requires every operation to support uncached execution. Setting this field to true overrides this requirement: instead, if the uncached interpreter tries to execute this operation, it will transition to cached and execute the cached operation.

      Bear in mind that the usefulness of such an interpreter depends on the frequency of the operation. For example, if a very common operation forces cached execution, it will cause most bytecode nodes to transition to cached, negating the intended benefits of an uncached interpreter.

      Since:
      24.2
      Default:
      false

    • tags

      Class<? extends Tag>[] tags
      The instrumentation tags that should be implicitly associated with this operation.
      Since:
      24.2
      See Also:
      Default:
      {}

    • javadoc

      String javadoc
      Optional documentation for the operation. This documentation is included in the javadoc for the generated interpreter.
      Since:
      24.2
      Default:
      ""