Package com.oracle.truffle.api.bytecode

Annotation Interface ConstantOperand

@Retention(SOURCE)
@Target(TYPE)
@Repeatable(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 (or endRoot if the operand is specified at the end).

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, constant operands appear before dynamic operands and are specified 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, constant operands appear before dynamic operands and are specified to the operation's begin method of the BytecodeBuilder. When specifyAtEnd() is true, the constant operand instead appears after dynamic operands and is specified to the operation's end 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 (except for Prologs, which receive their operands as arguments to

invalid reference

beginRoot

and

invalid reference

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