Package com.oracle.truffle.api.instrumentation

Interface ExecutionEventListener

public interface ExecutionEventListener
A listener attached by an Instrumenter to specific locations of a guest language program to listen to execution events.
Since:
0.12

  • Method Details

    • onEnter

      void onEnter(EventContext context, VirtualFrame frame)
      Invoked immediately before the instrumented node is executed. The order in which multiple event listeners are notified matches the order they are attached .
      Parameters:
      context - indicating the current location in the guest language AST
      frame - the frame that was used for executing instrumented node
      Since:
      0.12

    • onInputValue

      @Deprecated(since="20.0") default void onInputValue(EventContext context, VirtualFrame frame, EventContext inputContext, int inputIndex, Object inputValue)
      Deprecated.
      in 20.0. input value notifications are not functional for listeners. Use event node factories instead.
      Invoked immediately after each return value event of child nodes that match the input filter. Event listeners cannot save input values for later events. If that is required attach an event node factory instead.
      Parameters:
      context - indicating the current location in the guest language AST
      frame - the current frame in use
      inputContext - the event context of the input child node
      inputIndex - the child index of the input
      inputValue - the return value of the input child
      Since:
      0.30

    • onReturnValue

      void onReturnValue(EventContext context, VirtualFrame frame, Object result)
      Invoked immediately after an instrumented node is successfully executed. The order in which multiple event listeners are notified matches the order they are attached.
      Parameters:
      context - indicating the current location in the guest language AST
      frame - the frame that was used for executing instrumented node
      Since:
      0.12

    • onReturnExceptional

      void onReturnExceptional(EventContext context, VirtualFrame frame, Throwable exception)
      Invoked immediately after an instrumented node did not successfully execute. The order in which multiple event listeners are notified matches the order they are attached.

      When the exception is an instance of ThreadDeath the execution was abruptly interrupted. EventContext.createUnwind(Object) creates a ThreadDeath to unwind nodes off, for instance. Listener instances that threw an unwind throwable get called onUnwind(EventContext, VirtualFrame, Object) instead.

      Parameters:
      context - indicating the current location in the guest language AST
      frame - the frame that was used for executing instrumented node
      exception - the exception that occurred during the node's execution
      Since:
      0.12

    • onUnwind

      default Object onUnwind(EventContext context, VirtualFrame frame, Object info)
      Invoked when an instrumented node is unwound from the execution stack by unwind throwable thrown in this listener instance. Any nodes between the instrumented ones are unwound off without any notification. The default implementation returns null.
      Parameters:
      context - indicating the current location in the guest language AST
      frame - the frame that was used for executing instrumented node
      info - an info associated with the unwind - the object passed to EventContext.createUnwind(Object)
      Returns:
      null to continue to unwind the parent node, ProbeNode.UNWIND_ACTION_REENTER to reenter the current node, or an interop value to return that value early from the current node (void nodes just return, ignoring the return value).
      Since:
      0.31

    • onYield

      default void onYield(EventContext context, VirtualFrame frame, Object value)
      Invoked on a yield of the current thread. A yield interrupts the current execution, which is resumed later on. Delegates to onReturnValue(EventContext, VirtualFrame, Object) by default.
      Parameters:
      context - indicating the current location in the guest language AST
      frame - the frame that was used for executing instrumented node
      Since:
      24.0

    • onResume

      default void onResume(EventContext context, VirtualFrame frame)
      Invoked on a resume of the execution on the current thread after a yield. Delegates to onEnter(EventContext, VirtualFrame) by default.

      Use TruffleInstrument.Env.isSameFrame(RootNode, Frame, Frame) to match the interrupted and resumed execution.

      Parameters:
      context - indicating the current location in the guest language AST
      frame - the frame that was used for executing instrumented node
      Since:
      24.0