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

Nested Class Summary

Nested classes/interfaces inherited from class com.oracle.truffle.api.nodes.Node

Node.Child, Node.Children

Field Summary

Fields

Modifier and Type	Field and Description
static Object	UNWIND_ACTION_REENTER A constant that performs reenter of the current node when returned from ExecutionEventListener.onUnwind(EventContext, VirtualFrame, Object) or ExecutionEventNode.onUnwind(VirtualFrame, Object).

Method Summary

Modifier and Type	Method and Description
Node	copy() Creates a shallow copy of this node.
NodeCost	getCost() Returns a rough estimate for the cost of this Node.
void	onEnter(VirtualFrame frame) Should get invoked before the node is invoked.
Object	onReturnExceptionalOrUnwind(VirtualFrame frame, Throwable exception, boolean isReturnCalled) Should get invoked if the node did not complete successfully and handle a possible unwind.
void	onReturnValue(VirtualFrame frame, Object result) Should get invoked after the node is invoked successfully.

Methods inherited from class com.oracle.truffle.api.nodes.Node

accept, adoptChildren, atomic, atomic, deepCopy, getChildren, getDebugProperties, getDescription, getEncapsulatingSourceSection, getLock, getParent, getRootNode, getSourceSection, insert, insert, isAdoptable, isSafelyReplaceableBy, notifyInserted, onReplace, replace, replace, reportPolymorphicSpecialize, toString

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

UNWIND_ACTION_REENTER

public static final Object UNWIND_ACTION_REENTER

A constant that performs reenter of the current node when returned from ExecutionEventListener.onUnwind(EventContext, VirtualFrame, Object) or ExecutionEventNode.onUnwind(VirtualFrame, Object).

Since:

0.31

Method Detail

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:

result - the result value of the operation, must be an interop type (i.e. either implementing TruffleObject or be a primitive value), or null.

frame - the current frame of the execution.

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:

exception - the exception that occurred during the execution

frame - the current frame of the execution.

isReturnCalled - true when ProbeNode.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, 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

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