Package com.oracle.truffle.api.instrumentation

Class ProbeNode

java.lang.Object
com.oracle.truffle.api.nodes.Node
com.oracle.truffle.api.instrumentation.ProbeNode
All Implemented Interfaces:
NodeInterface, Cloneable
public final class ProbeNode extends Node

Represents an event sink for instrumentation events that is embedded in the AST using wrappers if needed. Instances of this class are provided by InstrumentableNode.createWrapper(ProbeNode) to notify the instrumentation API about execution events.

It is strongly recommended to use GenerateWrapper to generate implementations of wrapper nodes. If needed to be done manually then the recommended implementation of an execute method looks as follows: 
 @Override
 public Object execute(VirtualFrame frame) {
     Object returnValue;
     for (;;) {
         boolean wasOnReturnExecuted = false;
         try {
             probeNode.onEnter(frame);
             returnValue = delegateNode.executeGeneric(frame);
             wasOnReturnExecuted = true;
             probeNode.onReturnValue(frame, returnValue);
             break;
         } catch (Throwable t) {
             Object result = probeNode.onReturnExceptionalOrUnwind(frame, t, wasOnReturnExecuted);
             if (result == ProbeNode.UNWIND_ACTION_REENTER) {
                 continue;
             } else if (result != null) {
                 returnValue = result;
                 break;
             }
             throw t;
         }
     }
     return returnValue;
 }
Since:
0.12

  • Field Details

  • Method Details

    • onEnter

      public void onEnter(VirtualFrame frame)
      Should get invoked before the node is invoked.
      Parameters:
      frame - the current frame of the execution.
      Since:
      0.12

    • onReturnValue

      public void onReturnValue(VirtualFrame frame, Object result)
      Should get invoked after the node is invoked successfully.
      Parameters:
      frame - the current frame of the execution.
      result - the result value of the operation, must be an interop type (i.e. either implementing TruffleObject or be a primitive value), or null.
      Since:
      0.12

    • copy

      public Node copy()
      Creates a shallow copy of this node.
      Overrides:
      copy in class Node
      Returns:
      the new copy
      Since:
      0.31

    • onReturnExceptionalOrUnwind

      public Object onReturnExceptionalOrUnwind(VirtualFrame frame, Throwable exception, boolean isReturnCalled)
      Should get invoked if the node did not complete successfully and handle a possible unwind. When a non-null value is returned, a change of the execution path was requested by an unwind.
      Parameters:
      frame - the current frame of the execution.
      exception - the exception that occurred during the execution
      isReturnCalled - true when onReturnValue(VirtualFrame, Object) was called already for this node's execution, false otherwise. This helps to assure correct pairing of enter/return notifications.
      Returns:
      null to proceed to throw of the exception, 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

      public void onYield(VirtualFrame frame, Object result)
      Should be invoked when the node yields execution. Use GenerateWrapper.yieldExceptions() when possible, to have onYield() called automatically.

      When the yielded execution is resumed, call onResume(VirtualFrame), or use GenerateWrapper.resumeMethodPrefix().

      Parameters:
      frame - the current frame of the execution.
      Since:
      24.0

    • onResume

      public void onResume(VirtualFrame frame)
      Should be invoked when execution is resumed after a yield. Use GenerateWrapper.resumeMethodPrefix() when possible, to have this method called automatically by the wrapper node.

      Override RootNode.isSameFrame(Frame, Frame) if necessary, to be able to match the yielded and resumed executions.

      Parameters:
      frame - the current frame of the execution.
      Since:
      24.0

    • getCost

      public NodeCost getCost()
      Description copied from class: Node
      Returns a rough estimate for the cost of this Node. This estimate can be used by runtime systems or guest languages to implement heuristics based on Truffle ASTs. This method is intended to be overridden by subclasses. The default implementation returns the value of NodeInfo.cost() of the NodeInfo annotation declared at the subclass. If no NodeInfo annotation is declared the method returns NodeCost.MONOMORPHIC as a default value.
      Overrides:
      getCost in class Node
      Since:
      0.12