Annotation Interface ConstantOperand

@Retention(SOURCE) @Target(TYPE) @Repeatable(ConstantOperand.Repeat.class) public @interface ConstantOperand
Defines a constant operand for an operation. Constant operands are supported for Operation, Instrumentation, and Prolog operations.

Constant operands have a few benefits:

  • In contrast to dynamic operands, which are computed by executing the "children" of an operation at run time, constant operands are specified at parse time and require no run-time computation.
  • Constant operands have CompilerDirectives.CompilationFinal semantics. Though an interpreter can use LoadConstant operations to supply dynamic operands, those constants are not guaranteed to be compilation-final (the constant is pushed onto and then popped from the stack, which PE cannot always constant fold).
  • Instrumentation and Prolog operations are restricted and cannot encode arbitrary dynamic operands. Constant operands can be used to encode other information needed by these operations.
When an operation declares a constant operand, each specialization must declare a parameter for the operand before the dynamic operands. The parameter should have the exact type() of the constant operand.

When parsing the operation, a constant must be supplied as an additional parameter to the begin or emit method of the BytecodeBuilder. Constant operands to the Prolog should be supplied to the beginRoot method.

Except for RootNodes, a constant operand cannot be a subclass of Node. If an operation needs a compilation-final node operand, it can declare a NodeFactory constant operand and then declare a Cached parameter initialized with the result of createNode.

Since:
24.2

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    ConstantOperand.Repeat
    Repeat annotation for ConstantOperand.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    Class<?>
    type
    The type of the constant operand.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    dimensions
    Specifies the number of array dimensions to be marked as compilation final.
    String
    javadoc
    Optional documentation for the constant operand.
    String
    name
    Optional name for the constant operand.
    boolean
    specifyAtEnd
    By default, when an operation has dynamic operands, the constant operands appear before them in signatures and must be supplied to the operation's begin method of the BytecodeBuilder.

  • Element Details

    • type

      Class<?> type
      The type of the constant operand. All specializations must declare a parameter with this exact type.
      Since:
      24.2

    • name

      String name
      Optional name for the constant operand. When this field is not provided, the Bytecode DSL will infer a name from the specializations' parameters.
      Since:
      24.2
      Default:
      ""

    • javadoc

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

    • specifyAtEnd

      boolean specifyAtEnd
      By default, when an operation has dynamic operands, the constant operands appear before them in signatures and must be supplied to the operation's begin method of the BytecodeBuilder. When specifyAtEnd() is true, the constant operand instead appears after dynamic operands and is supplied to the operation's end method (constant operands to the Prolog can be supplied to the endRoot method).

      In some cases, it may be more convenient to specify a constant operand after parsing the child operations; for example, the constant may only be known after traversing child ASTs.

      This flag is meaningless if the operation does not take dynamic operands, since all constant operands will be supplied to a single emit method. The exception to this rule is Prologs, which can receive their operands as arguments to either beginRoot or endRoot.

      Since:
      24.2
      Default:
      false

    • dimensions

      int dimensions
      Specifies the number of array dimensions to be marked as compilation final. See CompilerDirectives.CompilationFinal.dimensions().

      The Bytecode DSL currently only supports a value of 0; that is, array elements are not compilation-final.

      Since:
      24.2
      Default:
      0