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.
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; }
Node.Child, Node.Children
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) . |
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.
|
accept, adoptChildren, atomic, atomic, deepCopy, getChildren, getDebugProperties, getDescription, getEncapsulatingSourceSection, getLock, getParent, getRootNode, getSourceSection, insert, insert, isAdoptable, isSafelyReplaceableBy, notifyInserted, onReplace, replace, replace, reportPolymorphicSpecialize, toString
public static final Object UNWIND_ACTION_REENTER
ExecutionEventListener.onUnwind(EventContext, VirtualFrame, Object)
or
ExecutionEventNode.onUnwind(VirtualFrame, Object)
.public void onEnter(VirtualFrame frame)
frame
- the current frame of the execution.public void onReturnValue(VirtualFrame frame, Object result)
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.public Node copy()
public Object onReturnExceptionalOrUnwind(VirtualFrame frame, Throwable exception, boolean isReturnCalled)
null
value is returned, a change of the execution path was requested
by an unwind
.exception
- the exception that occurred during the executionframe
- 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.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).public NodeCost getCost()
Node
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.