public abstract class ExecutionEventNode extends Node
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
.Node.Child, Node.Children
Modifier | Constructor and Description |
---|---|
protected |
ExecutionEventNode() |
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 |
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 |
saveInputValue(VirtualFrame frame,
int inputIndex,
Object inputValue)
Saves an input value reported by
ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object) for use in later events. |
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
protected void onEnter(VirtualFrame frame)
instrumented node
is executed. The order in which multiple event listeners are notified matches the order they
are
attached
.frame
- the current frame used in the instrumented nodeprotected void onInputValue(VirtualFrame frame, EventContext inputContext, int inputIndex, Object inputValue)
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.
frame
- the current frame in useinputContext
- the event context of the input child nodeinputIndex
- the child index of the inputinputValue
- the return value of the input childExecutionEventNode.saveInputValue(VirtualFrame, int, Object)
,
ExecutionEventNode.getSavedInputValues(VirtualFrame)
protected void onReturnValue(VirtualFrame frame, Object result)
instrumented node
is
successfully executed. The order in which multiple event listeners are notified matches the
order they are
attached
.frame
- the frame that was used for executing instrumented nodeprotected void onReturnExceptional(VirtualFrame frame, Throwable exception)
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
.frame
- the frame that was used for executing instrumented nodeexception
- the exception that occurred during the node's executionprotected Object onUnwind(VirtualFrame frame, Object info)
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.frame
- the frame that was used for executing instrumented nodeinfo
- an info associated with the unwind - the object passed to
EventContext.createUnwind(Object)
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).protected void onDispose(VirtualFrame frame)
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.frame
- the frame that was used for executing instrumented nodeprotected final EventContext getInputContext(int index)
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.index
- the context indexIndexOutOfBoundsException
- if the index is out of bounds.ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object)
,
ExecutionEventNode.getInputCount()
protected final int getInputCount()
input events
when executed.ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object)
protected final void saveInputValue(VirtualFrame frame, int inputIndex, Object inputValue)
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
.frame
- the frame to store the input value ininputIndex
- the child input indexinputValue
- the input valueIllegalArgumentException
- for invalid input indexes for non-existing input nodes.ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object)
protected final Object[] getSavedInputValues(VirtualFrame frame)
null
is returned. If all inputs were filtered or a null
input
filter was provided then an empty array is returned.frame
- the frame to read the input values from.ExecutionEventNode.saveInputValue(VirtualFrame, int, Object)
,
ExecutionEventNode.onInputValue(VirtualFrame, EventContext, int, Object)