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

Nested Class Summary

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

Node.Child, Node.Children

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ExecutionEventNode()

Method Summary

Modifier and Type	Method and Description
protected EventContext	getInputContext(int index) Returns the event context of an input by index.
protected int	getInputCount() Returns the total number of instrumented input nodes that may produce input events when executed.
protected Object[]	getSavedInputValues(VirtualFrame frame) Returns all saved input values.
protected void	onDispose(VirtualFrame frame) Invoked when an event node is removed from the AST.
protected void	onEnter(VirtualFrame frame) Invoked immediately before the instrumented node is executed.
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.
protected void	onResume(VirtualFrame frame) Invoked on a resume of the execution on the current thread after a yield.
protected void	onReturnExceptional(VirtualFrame frame, Throwable exception) Invoked immediately after the execution of an instrumented node resulted in an exception.
protected void	onReturnValue(VirtualFrame frame, Object result) Invoked immediately after an instrumented node is successfully executed.
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.
protected void	onYield(VirtualFrame frame, Object value) Invoked on a yield of the current thread.
protected void	saveInputValue(VirtualFrame frame, int inputIndex, Object inputValue) Saves an input value reported by ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object) for use in later events.

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

accept, adoptChildren, atomic, atomic, copy, 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, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ExecutionEventNode

protected ExecutionEventNode()

Since:

0.12

Method Detail

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 ExecutionEventNode.getInputCount(). Other input contexts than the currently input context can be accessed using ExecutionEventNode.getInputContext(int).

Input values can be saved to make them ExecutionEventNode.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:

ExecutionEventNode.saveInputValue(VirtualFrame, int, Object), ExecutionEventNode.getSavedInputValues(VirtualFrame)

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 ExecutionEventNode.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 ExecutionEventNode.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 ExecutionEventNode.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 ExecutionEventNode.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 ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object). The total number of instrumented input nodes can be accessed using ExecutionEventNode.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:

ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object), ExecutionEventNode.getInputCount()

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:

ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object)

saveInputValue

protected final void saveInputValue(VirtualFrame frame,
                                    int inputIndex,
                                    Object inputValue)

Saves an input value reported by ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object) for use in later events. Saved input values can be restored using ExecutionEventNode.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:

ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object)

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:

ExecutionEventNode.saveInputValue(VirtualFrame, int, Object), ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object)