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 may extend other static classes to inherit specializations, but they must adhere to the same restrictions as operation classes. This is useful to share common specializations across multiple operations.
  • 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.
    boolean
    storeBytecodeIndex
    Indicates whether this operation requires the bytecode index to be updated.
    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:
      ""

    • storeBytecodeIndex

      boolean storeBytecodeIndex
      Indicates whether this operation requires the bytecode index to be updated. By default, the DSL assumes that all operations with caches require the bytecode index to be updated. The DSL will emit a warning if specifying this attribute is necessary.

      If this attribute has been set to false, then the StoreBytecodeIndex annotation can be used to enable this property for individual Specialization or Fallback-annotated methods.

      This annotation only has an effect if GenerateBytecode.storeBytecodeIndexInFrame() is set to true or if the uncached interpreter tier is enabled.

      Since:
      25.1
      See Also:
      Default:
      true