Package com.oracle.truffle.api.instrumentation

Class ExecutionEventNode

java.lang.Object
com.oracle.truffle.api.nodes.Node
com.oracle.truffle.api.instrumentation.ExecutionEventNode
All Implemented Interfaces:
NodeInterface, Cloneable
public abstract class ExecutionEventNode extends Node
An event node created by an ExecutionEventNodeFactory for a specific locations of a guest language program to listen to instrumentation events. In addition to listeners event nodes allow to store state for a particular program location.
Since:
0.12

  • Constructor Details

    • ExecutionEventNode

      protected ExecutionEventNode()
      Since:
      0.12

  • Method Details

    • onEnter

      protected void onEnter(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:
      frame - the current frame used in the instrumented node
      Since:
      0.12

    • onInputValue

      protected void onInputValue(VirtualFrame frame, EventContext inputContext, int inputIndex, Object inputValue)
      Invoked immediately after each return value event of instrumented input child node that match the input filter. Whether, when and how often input child value events are triggered depends on the semantics of the instrumented node. For example, if the instrumented node represents binary arithmetic then two input value events will be triggered for index 0 and 1. For short-circuited child values not all input child nodes may be executed therefore they might not trigger events for all inputs. For instrumented loop nodes input value events with the same index may be triggered many times.

      The total number of input nodes that may produce input events can be accessed using getInputCount(). Other input contexts than the currently input context can be accessed using getInputContext(int).

      Input values can be saved to make them getSavedInputValues(VirtualFrame) accessible in onReturn or onReturnExceptional events.

      Parameters:
      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.33
      See Also:

    • onReturnValue

      protected void onReturnValue(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:
      frame - the frame that was used for executing instrumented node
      Since:
      0.12

    • onReturnExceptional

      protected void onReturnExceptional(VirtualFrame frame, Throwable exception)
      Invoked immediately after the execution of an instrumented node resulted in an exception. Note that this could be a ControlFlowException, which is expected and considered a successful execution of the node. The order in which multiple event listeners are notified matches the order they are attached.
      Parameters:
      frame - the frame that was used for executing instrumented node
      exception - the exception that occurred during the node's execution
      Since:
      0.12

    • onUnwind

      protected Object onUnwind(VirtualFrame frame, Object info)
      Invoked when an instrumented node is unwound from the execution stack by unwind throwable thrown in this node implementation. Any nodes between the instrumented ones are unwound off without any notification. The default implementation returns null to indicate continue unwind.
      Parameters:
      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

      protected void onYield(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(VirtualFrame, Object) by default.
      Parameters:
      frame - the frame that was used for executing instrumented node
      Since:
      24.0

    • onResume

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

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

      Parameters:
      frame - the frame that was used for executing instrumented node
      Since:
      24.0

    • onDispose

      protected void onDispose(VirtualFrame frame)
      Invoked when an event node is removed from the AST. This happens if the underlying binding, language/instrument or engine is disposed. Event nodes are removed lazily. This means that onDispose(VirtualFrame) is invoked the next time the particular part of the AST is executed. If the instrumented node is not invoked anymore after it was disposed then onDispose(VirtualFrame) might or might not be executed.
      Parameters:
      frame - the frame that was used for executing instrumented node
      Since:
      0.12

    • getInputContext

      protected final EventContext getInputContext(int index)
      Returns the event context of an input by index. The returned input context matches the input context provided in onInputValue(VirtualFrame, EventContext, int, Object). The total number of instrumented input nodes can be accessed using getInputCount(). This method returns a constant event context for a constant input index, when called in partially evaluated code paths.
      Parameters:
      index - the context index
      Throws:
      IndexOutOfBoundsException - if the index is out of bounds.
      Since:
      0.33
      See Also:

    • getInputCount

      protected final int getInputCount()
      Returns the total number of instrumented input nodes that may produce input events when executed.
      Since:
      0.33
      See Also:

    • saveInputValue

      protected final void saveInputValue(VirtualFrame frame, int inputIndex, Object inputValue)
      Saves an input value reported by onInputValue(VirtualFrame, EventContext, int, Object) for use in later events. Saved input values can be restored using getSavedInputValues(VirtualFrame) in onReturn or onReturnExceptional events. The implementation ensures that a minimal number of frame slots is used to save input values. It uses the AST structure to reuse frame slots efficiently whenever possible. The used frame slots are freed if the event binding is disposed.
      Parameters:
      frame - the frame to store the input value in
      inputIndex - the child input index
      inputValue - the input value
      Throws:
      IllegalArgumentException - for invalid input indexes for non-existing input nodes.
      Since:
      0.33
      See Also:

    • getSavedInputValues

      protected final Object[] getSavedInputValues(VirtualFrame frame)
      Returns all saved input values. For valid input indices that did not save any value null is returned. If all inputs were filtered or a null input filter was provided then an empty array is returned.
      Parameters:
      frame - the frame to read the input values from.
      Since:
      0.33
      See Also: