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

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	Description
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).

Method Summary

Modifier and Type	Method	Description
Node	copy()	Creates a shallow copy of this node.
void	onEnter(VirtualFrame frame)	Should get invoked before the node is invoked.
void	onResume(VirtualFrame frame)	Should be invoked when execution is resumed after a yield.
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.
void	onYield(VirtualFrame frame, Object result)	Should be invoked when the node yields execution.

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

accept, adoptChildren, atomic, atomic, deepCopy, getChildren, getCost, 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, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

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 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