com.oracle.truffle.api.instrumentation

Interface ExecutionEventListener

public interface ExecutionEventListener

A listener attached by an Instrumenter to specific locations of a guest language program to listen to execution events.

Since:

0.12

Method Summary

Modifier and Type	Method and Description
void	onEnter(EventContext context, VirtualFrame frame) Invoked immediately before the instrumented node is executed.
void	onReturnExceptional(EventContext context, VirtualFrame frame, Throwable exception) Invoked immediately after an instrumented node did not successfully execute.
void	onReturnValue(EventContext context, VirtualFrame frame, Object result) Invoked immediately after an instrumented node is successfully executed.
default Object	onUnwind(EventContext context, VirtualFrame frame, Object info) Invoked when an instrumented node is unwound from the execution stack by unwind throwable thrown in this listener instance.

Method Detail

onEnter

void onEnter(EventContext context,
             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:

context - indicating the current location in the guest language AST

frame - the frame that was used for executing instrumented node

Since:

0.12

onReturnValue

void onReturnValue(EventContext context,
                   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:

context - indicating the current location in the guest language AST

frame - the frame that was used for executing instrumented node

Since:

0.12

onReturnExceptional

void onReturnExceptional(EventContext context,
                         VirtualFrame frame,
                         Throwable exception)

Invoked immediately after an instrumented node did not successfully execute. The order in which multiple event listeners are notified matches the order they are attached.

When the exception is an instance of ThreadDeath the execution was abruptly interrupted. EventContext.createUnwind(Object) creates a ThreadDeath to unwind nodes off, for instance. Listener instances that threw an unwind throwable get called ExecutionEventListener.onUnwind(EventContext, VirtualFrame, Object) instead.

Parameters:

context - indicating the current location in the guest language AST

frame - the frame that was used for executing instrumented node

exception - the exception that occurred during the node's execution

Since:

0.12

onUnwind

default Object onUnwind(EventContext context,
                        VirtualFrame frame,
                        Object info)

Invoked when an instrumented node is unwound from the execution stack by unwind throwable thrown in this listener instance. Any nodes between the instrumented ones are unwound off without any notification. The default implementation returns null.

Parameters:

context - indicating the current location in the guest language AST

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