Interface BytecodeRootNode

public interface BytecodeRootNode
Base interface to be implemented by the bytecode root node of a Bytecode DSL interpreter. The bytecode root node should extend RootNode and be annotated with @GenerateBytecode.

The current bytecode root node can be bound inside operations using @Bind. For example, if the bytecode root node class is MyBytecodeRootNode, it can be bound using @Bind MyBytecodeRootNode root.

Bytecode root nodes can declare a TypeSystemReference that will be inherited by all declared operations (including operation proxies). Operations can also declare their own type system references to override the root type system.

Since:
24.2
See Also:

  • Method Details

    • execute

      Object execute(VirtualFrame frame)
      Entrypoint to the root node.

      This method will be generated by the Bytecode DSL. Do not override.

      Parameters:
      frame - the frame used for execution
      Returns:
      the value returned by the root node
      Since:
      24.2

    • interceptControlFlowException

      default Object interceptControlFlowException(ControlFlowException ex, VirtualFrame frame, BytecodeNode bytecodeNode, int bytecodeIndex) throws Throwable
      Optional hook invoked when a ControlFlowException is thrown during execution. This hook can do one of four things:
      1. It can return a value. The value will be returned from the root node (this can be used to implement early returns).
      2. It can throw the same or a different ControlFlowException. The thrown exception will be thrown from the root node.
      3. It can throw an AbstractTruffleException. The thrown exception will be forwarded to the guest code for handling.
      4. It can throw an internal error, which will be intercepted by interceptInternalException(Throwable, VirtualFrame, BytecodeNode, int).
      Parameters:
      ex - the control flow exception
      frame - the frame at the point the exception was thrown
      bytecodeNode - the bytecode node executing when the exception was thrown
      bytecodeIndex - the bytecode index of the instruction that caused the exception
      Throws:
      Throwable
      Since:
      24.2

    • interceptInternalException

      default Throwable interceptInternalException(Throwable t, VirtualFrame frame, BytecodeNode bytecodeNode, int bytecodeIndex)
      Optional hook invoked when an internal exception (i.e., anything other than AbstractTruffleException or ControlFlowException) is thrown during execution. This hook can be used to convert such exceptions into guest-language exceptions that can be handled by guest code.

      For example, if a Java StackOverflowError is thrown, this hook can be used to return a guest-language equivalent exception that the guest code understands.

      If the return value is an AbstractTruffleException, it will be forwarded to the guest code for handling. The exception will also be intercepted by interceptTruffleException(AbstractTruffleException, VirtualFrame, BytecodeNode, int).

      If the return value is not an AbstractTruffleException, it will be rethrown. Thus, if an internal error cannot be converted to a guest exception, it can simply be returned.

      Parameters:
      t - the internal exception
      frame - the frame at the point the exception was thrown
      bytecodeNode - the bytecode node executing when the exception was thrown
      bytecodeIndex - the bytecode index of the instruction that caused the exception
      Returns:
      an equivalent guest-language exception or an exception to be rethrown
      Since:
      24.2

    • interceptTruffleException

      default AbstractTruffleException interceptTruffleException(AbstractTruffleException ex, VirtualFrame frame, BytecodeNode bytecodeNode, int bytecodeIndex)
      Optional hook invoked when an AbstractTruffleException is thrown during execution. This hook can be used to preprocess the exception or replace it with another exception before it is handled.
      Parameters:
      ex - the Truffle exception
      frame - the frame at the point the exception was thrown
      bytecodeNode - the bytecode node executing when the exception was thrown
      bytecodeIndex - the bytecode index of the instruction that caused the exception
      Returns:
      the Truffle exception to be handled by guest code
      Since:
      24.2

    • getBytecodeNode

      default BytecodeNode getBytecodeNode()
      Returns the current bytecode node. Note that the bytecode may change at any point in time.

      This method will be generated by the Bytecode DSL. Do not override.

      Returns:
      the current bytecode node
      Since:
      24.2

    • getRootNodes

      default BytecodeRootNodes<?> getRootNodes()
      Returns the BytecodeRootNodes instance associated with this root node.

      This method will be generated by the Bytecode DSL. Do not override.

      Since:
      24.2

    • getStartLocation

      default BytecodeLocation getStartLocation()
      Returns the location associated with the start of this root node.
      Since:
      24.2

    • ensureSourceSection

      default SourceSection ensureSourceSection()
      Returns the source section for this root node and materializes source information if it was not yet materialized.
      Since:
      24.2
      See Also:

    • dump

      default String dump()
      Helper method to dump the root node's bytecode.
      Returns:
      a string representation of the bytecode
      Since:
      24.2