Class Instruction

java.lang.Object
com.oracle.truffle.api.bytecode.Instruction
public abstract class Instruction extends Object
Represents metadata for an instruction in a bytecode node.

Compatibility note: The data contained in instruction classes is subject to change without notice between Truffle versions. This introspection API is therefore intended to be used for debugging and tracing purposes only. Do not rely on instructions for your language semantics.

The current instruction can be bound using @Bind Instruction instruction from operations. This class is not intended to be subclassed by clients, only by code generated by the Bytecode DSL.

Since:
24.2
See Also:

  • Constructor Details

    • Instruction

      protected Instruction(Object token)
      Internal constructor for generated code. Do not use.
      Since:
      24.2

  • Method Details

    • getBytecodeNode

      public abstract BytecodeNode getBytecodeNode()
      Returns the bytecode node this instruction belongs to.
      Since:
      24.2

    • getBytecodeIndex

      public abstract int getBytecodeIndex()
      Returns the bytecode index of this instruction. A bytecode index is only valid for a given BytecodeNode, it is therefore recommended to use getLocation() instead whenever possible.
      Since:
      24.2
      See Also:

    • getLength

      public abstract int getLength()
      Returns the length of this instruction in bytes.
      Since:
      24.2

    • getLocation

      public final BytecodeLocation getLocation()
      Converts this instruction pointer into a bytecode location. It is recommended to use BytecodeLocation to persist a bytecode location instead of using instruction.
      Since:
      24.2

    • getName

      public abstract String getName()
      Returns the name of this instruction. The name of the instruction is purely for human consumption and no structure should be assumed. If two instructions have the same instruction name then they also have the same operation code.

      The name is fixed for an Instruction object, but the name of an instruction at a particular location can change during execution due to quickening and other optimizations.

      Since:
      24.2
      See Also:

    • getOperationCode

      public abstract int getOperationCode()
      Returns the operation code of this instruction. The operation code of the instruction is purely for human consumption and no values should be assumed. If two instructions have the same instruction operation code then they also have the same name.

      The operation code is fixed for an Instruction object, but the operation code of an instruction at a particular location can change during execution due to quickening and other optimizations.

      Since:
      24.2
      See Also:

    • getArguments

      public abstract List<Instruction.Argument> getArguments()
      Returns an immutable list of immediate arguments for this instructions. The number and kinds of arguments remain stable during execution, however, the actual values of the arguments (e.g., Instruction.Argument.asBranchProfile()) may change during execution.
      Since:
      24.2

    • isInstrumentation

      public abstract boolean isInstrumentation()
      Returns true if this instruction represents a bytecode or tag instrumentation instruction, else false. Instrumentation instructions may get inserted dynamically during execution, e.g., if a tag is materialized or an Instrumentation is configured.
      Since:
      24.2

    • getSourceSection

      public final SourceSection getSourceSection()
      Returns the most concrete source section associated with this instruction. If no source section is available for this instruction or source sections have not yet been materialized, then null is returned. Source sections may be materialized by calling update with BytecodeConfig.WITH_SOURCE.
      Since:
      24.2

    • getSourceSections

      public final SourceSection[] getSourceSections()
      Returns all source section associated with this instruction starting with the most concrete source section. If no source sections are available, then an empty array is returned. If source sections have not yet been materialized, then null is returned. Source sections may be materialized by calling update with BytecodeConfig.WITH_SOURCE.
      Since:
      24.2

    • getNextBytecodeIndex

      public final int getNextBytecodeIndex()
      Returns the bytecode index of the next instruction. This method is useful to quickly find the next instruction. The next bytecode index is computed as getBytecodeIndex() + getLength().

      The next bytecode index may not be a valid index if this instruction is the last instruction. Use BytecodeNode.getInstructions() to walk all instructions efficiently and safely. Since the bytecode encoding is variable length, there is no efficient way to get to the previous bytecode index. Only forward traversial is efficient. If random access is desired use BytecodeNode.getInstructionsAsList().

      Since:
      24.2

    • next

      protected abstract Instruction next()
      Returns the next instruction object. Implemented by generated code, intended for internal use only.
      Since:
      24.2

    • hashCode

      public final int hashCode()
      Overrides:
      hashCode in class Object
      Since:
      24.2

    • equals

      public final boolean equals(Object obj)
      Overrides:
      equals in class Object
      Since:
      24.2

    • toString

      public final String toString()
      Overrides:
      toString in class Object
      Since:
      24.2