Package com.oracle.truffle.api.bytecode

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 value 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 at least package-private visibility. It should not extend/implement any other class/interface.
  • The operation class should not contain instance members.
  • The specializations also have some differences:
    • Specializations should be static and 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
    String
    javadoc
    Optional documentation for the operation.
    Class<? extends Tag>[]
    tags
    The instrumentation tags that should be implicitly associated with this operation.

  • Element Details

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