com.oracle.truffle.api.instrumentation

Class Instrumenter

java.lang.Object

com.oracle.truffle.api.instrumentation.Instrumenter

public abstract class Instrumenter
extends Object

Provides capabilities to attach listeners for execution, load, output and allocation events. The instrumenter remains usable as long as the engine is not closed. The instrumenter methods are safe to be used from arbitrary other threads.

Since:

0.12

Method Summary

Modifier and Type	Method and Description
abstract <T extends AllocationListener> EventBinding<T>	attachAllocationListener(AllocationEventFilter filter, T listener) Attach a listener to be notified about allocations of guest language values.
abstract <T extends ContextsListener> EventBinding<T>	attachContextsListener(T listener, boolean includeActiveContexts) Attach a listener to be notified about changes in contexts in guest language application.
abstract <T extends OutputStream> EventBinding<T>	attachErrConsumer(T stream) Attach an output stream as a consumer of the error output .
abstract <T extends ExecuteSourceListener> EventBinding<T>	attachExecuteSourceListener(SourceFilter filter, T listener, boolean includeExecutedSources) Starts notifications for each newly executed Source and returns a binding that can be used to terminate notifications.
abstract <T extends ExecutionEventNodeFactory> EventBinding<T>	attachExecutionEventFactory(NearestSectionFilter nearestFilter, SourceSectionFilter baseFilter, T factory) Starts execution event notification for the nearest SourceSection as specified by the NearestSectionFilter.
abstract <T extends ExecutionEventNodeFactory> EventBinding<T>	attachExecutionEventFactory(SourceSectionFilter eventFilter, SourceSectionFilter inputFilter, T factory) Starts execution event notification for a given event filter and factory.
<T extends ExecutionEventNodeFactory> EventBinding<T>	attachExecutionEventFactory(SourceSectionFilter eventFilter, T factory) Starts execution event notification for a given event filter and factory.
<T extends ExecutionEventListener> EventBinding<T>	attachExecutionEventListener(SourceSectionFilter eventFilter, T listener) Starts execution event notification for a given event filter and listener.
abstract <T extends LoadSourceListener> EventBinding<T>	attachLoadSourceListener(SourceFilter filter, T listener, boolean includeExistingSources) Starts notifications for each newly loaded Source and returns a binding that can be used to terminate notifications.
abstract <T extends LoadSourceSectionListener> EventBinding<T>	attachLoadSourceSectionListener(NearestSectionFilter nearestFilter, SourceSectionFilter baseFilter, T listener, boolean includeExistingSourceSections) Starts notifications for the nearest SourceSection as specified by the NearestSectionFilter and returns a binding that can be used to terminate notifications.
abstract <T extends LoadSourceSectionListener> EventBinding<T>	attachLoadSourceSectionListener(SourceSectionFilter filter, T listener, boolean includeExistingSourceSections) Starts notifications for each SourceSection in every newly loaded Source and returns a binding that can be used to terminate notifications.
abstract <T extends OutputStream> EventBinding<T>	attachOutConsumer(T stream) Attach an output stream as a consumer of the standard output.
abstract EventBinding<? extends ThreadsActivationListener>	attachThreadsActivationListener(ThreadsActivationListener listener) Attach a listener to be notified about when a thread gets entered or left in guest language applications.
abstract <T extends ThreadsListener> EventBinding<T>	attachThreadsListener(T listener, boolean includeInitializedThreads) Attach a listener to be notified about changes in threads in guest language application.
abstract <T extends ExecuteSourceListener> EventBinding<T>	createExecuteSourceBinding(SourceFilter filter, T listener, boolean includeExecutedSources) Create a binding to get notifications for each newly executed Source.
abstract <T extends LoadSourceListener> EventBinding<T>	createLoadSourceBinding(SourceFilter filter, T listener, boolean includeExistingSources) Create a binding to get notifications for each newly loaded Source.
abstract <T extends LoadSourceSectionListener> EventBinding<T>	createLoadSourceSectionBinding(NearestSectionFilter nearestFilter, SourceSectionFilter baseFilter, T listener, boolean includeExistingSourceSections) Create a binding to get notification for the nearest source section to the given position as specified by the NearestSectionFilter.
abstract <T extends LoadSourceSectionListener> EventBinding<T>	createLoadSourceSectionBinding(SourceSectionFilter filter, T listener, boolean includeExistingSourceSections) Create a binding to get notifications for each newly loaded SourceSection in every newly loaded Source.
abstract ExecutionEventNode	lookupExecutionEventNode(Node node, EventBinding<?> binding) Returns the execution event node that was inserted at the node's location given an event binding, if any.
List<SourceSection>	querySourceSections(SourceSectionFilter filter) Returns a filtered list of loaded SourceSection instances.
abstract Set<Class<?>>	queryTags(Node node) Returns an unmodifiable Set of tag classes which where associated with this node.
abstract void	visitLoadedSourceSections(SourceSectionFilter filter, LoadSourceSectionListener listener) Notifies the listener for each SourceSection in every loaded Source that corresponds to the filter.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

attachExecutionEventListener

public final <T extends ExecutionEventListener> EventBinding<T> attachExecutionEventListener(SourceSectionFilter eventFilter,
                                                                                             T listener)

Starts execution event notification for a given event filter and listener. The execution events are delivered to the ExecutionEventListener.

Returns a binding which allows to dispose the attached execution event binding. Disposing the binding removes all probes and wrappers from the AST that were created for this instrument. The removal of probes and wrappers is performed lazily on the next execution of the AST.

By default no input value events are delivered to the listener.

Parameters:

eventFilter - filters the events that are reported to the given listener

listener - that listens to execution events.

Since:

0.33

See Also:

ExecutionEventListener

attachExecutionEventFactory

public final <T extends ExecutionEventNodeFactory> EventBinding<T> attachExecutionEventFactory(SourceSectionFilter eventFilter,
                                                                                               T factory)

Starts execution event notification for a given event filter and factory. Events are delivered to the ExecutionEventNode instances created by the factory.

Returns a binding which allows to dispose the attached execution event binding. Disposing the binding removes all probes and wrappers from the AST that were created for this instrument. The removal of probes and wrappers is performed lazily on the next execution of the AST.

By default no input value events are delivered to the created execution event nodes. To deliver inputs events use Instrumenter.attachExecutionEventFactory(SourceSectionFilter, SourceSectionFilter, ExecutionEventNodeFactory) instead.

Parameters:

eventFilter - filters the events that are reported to the execution event nodes created by the factory.

factory - the factory that creates execution event nodes.

Since:

0.33

See Also:

ExecutionEventNodeFactory, Instrumenter.attachExecutionEventFactory(SourceSectionFilter, SourceSectionFilter, ExecutionEventNodeFactory)

attachExecutionEventFactory

public abstract <T extends ExecutionEventNodeFactory> EventBinding<T> attachExecutionEventFactory(SourceSectionFilter eventFilter,
                                                                                                  SourceSectionFilter inputFilter,
                                                                                                  T factory)

Starts execution event notification for a given event filter and factory. Events are delivered to the ExecutionEventNode instances created by the factory.

Returns a binding which allows to dispose the attached execution event binding. Disposing the binding removes all probes and wrappers from the AST that were created for this instrument. The removal of probes and wrappers is performed lazily on the next execution of the AST.

The input filter argument filters which input events are delivered to the created execution event nodes.

Parameters:

eventFilter - filters the events that are reported to the execution event nodes created by the factory.

inputFilter - filters input events, null for no input values

factory - the factory that creates execution event nodes.

Since:

0.33

See Also:

ExecutionEventNodeFactory, ExecutionEventNode.onInputValue(com.oracle.truffle.api.frame.VirtualFrame, EventContext, int, Object)

attachExecutionEventFactory

public abstract <T extends ExecutionEventNodeFactory> EventBinding<T> attachExecutionEventFactory(NearestSectionFilter nearestFilter,
                                                                                                  SourceSectionFilter baseFilter,
                                                                                                  T factory)

Starts execution event notification for the nearest SourceSection as specified by the NearestSectionFilter. Events are delivered to the ExecutionEventNode instances created by the factory.

Returns a binding which allows to dispose the attached execution event binding. Disposing the binding removes all probes and wrappers from the AST that were created for this instrument. The removal of probes and wrappers is performed lazily on the next execution of the AST.

The final nearest node is selected from the sections filtered by the baseFilter by applying InstrumentableNode.findNearestNodeAt(int, int, Set).

Parameters:

nearestFilter - a filter describing the nearest section

baseFilter - a filter selecting sections we find the nearest from

factory - the factory that creates execution event nodes.

Returns:

a handle to dispose the execution event binding.

Since:

23.0

See Also:

ExecutionEventNodeFactory

attachLoadSourceListener

public abstract <T extends LoadSourceListener> EventBinding<T> attachLoadSourceListener(SourceFilter filter,
                                                                                        T listener,
                                                                                        boolean includeExistingSources)

Starts notifications for each newly loaded Source and returns a binding that can be used to terminate notifications. Only subsequent loads will be notified unless includeExistingSources is true, in which case a notification for each previous load will be delivered before this method returns.

Parameters:

filter - a filter on which sources events are triggered.

listener - a listener that gets notified if a source was loaded

includeExistingSources - whether or not this listener should be notified for sources which were already loaded at the time when this listener was attached.

Returns:

a handle for stopping the notification stream

Since:

0.33

See Also:

LoadSourceListener.onLoad(LoadSourceEvent)

attachExecuteSourceListener

public abstract <T extends ExecuteSourceListener> EventBinding<T> attachExecuteSourceListener(SourceFilter filter,
                                                                                              T listener,
                                                                                              boolean includeExecutedSources)

Starts notifications for each newly executed Source and returns a binding that can be used to terminate notifications. Only subsequent executions will be notified unless includeExecutedSources is true, in which case a notification for each previously executed source will be delivered before this method returns. A source is reported as executed if any of it's RootNodes start to be executed. Every source is reported at most once.

Parameters:

filter - a filter on which source events are triggered.

listener - a listener that gets notified if a source was executed

includeExecutedSources - whether or not this listener should be notified for sources which were already executed at the time when this listener was attached.

Returns:

a handle for stopping the notification stream

Since:

0.33

See Also:

ExecuteSourceListener.onExecute(ExecuteSourceEvent)

attachLoadSourceSectionListener

public abstract <T extends LoadSourceSectionListener> EventBinding<T> attachLoadSourceSectionListener(SourceSectionFilter filter,
                                                                                                      T listener,
                                                                                                      boolean includeExistingSourceSections)

Starts notifications for each SourceSection in every newly loaded Source and returns a binding that can be used to terminate notifications. Only subsequent loads will be notified unless includeExistingSourceSections is true, in which case a notification for each previous load will be delivered before this method returns. Every source is reported at most once.

Parameters:

filter - a filter on which sources sections trigger events

listener - a listener that gets notified if a source section was loaded

includeExistingSourceSections - whether or not this listener should be notified for sources which were already loaded at the time when this listener was attached.

Returns:

a handle for stopping the notification stream

Since:

0.15

See Also:

LoadSourceSectionListener.onLoad(LoadSourceSectionEvent)

attachLoadSourceSectionListener

public abstract <T extends LoadSourceSectionListener> EventBinding<T> attachLoadSourceSectionListener(NearestSectionFilter nearestFilter,
                                                                                                      SourceSectionFilter baseFilter,
                                                                                                      T listener,
                                                                                                      boolean includeExistingSourceSections)

Starts notifications for the nearest SourceSection as specified by the NearestSectionFilter and returns a binding that can be used to terminate notifications. The final nearest node is selected from the sections filtered by the baseFilter by applying InstrumentableNode.findNearestNodeAt(int, int, Set). Only subsequent loads will be notified unless includeExistingSourceSections is true, in which case a notification for each previously loaded source section will be delivered before this method returns.

Parameters:

nearestFilter - a filter describing the nearest section

baseFilter - a filter selecting sections we find the nearest from

listener - a listener that gets notified if a source section was loaded

includeExistingSourceSections - whether or not this listener should be notified for source sections which were already loaded at the time when this listener was attached.

Returns:

a handle for stopping the notification stream

Since:

23.0

See Also:

LoadSourceSectionListener.onLoad(LoadSourceSectionEvent)

createLoadSourceBinding

public abstract <T extends LoadSourceListener> EventBinding<T> createLoadSourceBinding(SourceFilter filter,
                                                                                       T listener,
                                                                                       boolean includeExistingSources)

Create a binding to get notifications for each newly loaded Source. The binding needs to be attached to receive notifications. Only subsequent loads will be notified after attach, unless includeExistingSources is true, in which case a notification for each previously loaded source will be delivered before attach method returns.

The difference from Instrumenter.attachLoadSourceListener(SourceFilter, LoadSourceListener, boolean) is in having the binding object before notifications are produced when existing sources are requested.

Parameters:

filter - a filter on which sources events are triggered.

listener - a listener that gets notified if a source was loaded

includeExistingSources - whether or not this listener should be notified for sources which were already loaded at the time when this listener was attached.

Returns:

a binding handle to attach and stop the notification stream

Since:

21.1

See Also:

LoadSourceListener.onLoad(LoadSourceEvent)

createExecuteSourceBinding

public abstract <T extends ExecuteSourceListener> EventBinding<T> createExecuteSourceBinding(SourceFilter filter,
                                                                                             T listener,
                                                                                             boolean includeExecutedSources)

Create a binding to get notifications for each newly executed Source. The binding needs to be attached to receive notifications. Only subsequent executions will be notified after attach, unless includeExecutedSources is true, in which case a notification for each previously executed source will be delivered before attach method returns. Every source is reported at most once.

The difference from Instrumenter.attachExecuteSourceListener(SourceFilter, ExecuteSourceListener, boolean) is in having the binding object before notifications are produced when executed sources are requested.

Parameters:

filter - a filter on which sources events are triggered.

listener - a listener that gets notified if a source was executed

includeExecutedSources - whether or not this listener should be notified for sources which were already executed at the time when this listener was attached.

Returns:

a binding handle to attach and stop the notification stream

Since:

21.1

See Also:

ExecuteSourceListener.onExecute(ExecuteSourceEvent)

createLoadSourceSectionBinding

public abstract <T extends LoadSourceSectionListener> EventBinding<T> createLoadSourceSectionBinding(SourceSectionFilter filter,
                                                                                                     T listener,
                                                                                                     boolean includeExistingSourceSections)

Create a binding to get notifications for each newly loaded SourceSection in every newly loaded Source. The binding needs to be attached to receive notifications. Only subsequent loads will be notified after attach, unless includeExistingSourceSections is true, in which case a notification for each previously loaded source section will be delivered before attach method returns. Every source is reported at most once.

The difference from Instrumenter.attachLoadSourceSectionListener(SourceSectionFilter, LoadSourceSectionListener, boolean) is in having the binding object before notifications are produced when existing source sections are requested.

Parameters:

filter - a filter on which sources events are triggered.

listener - a listener that gets notified if a source section was loaded

includeExistingSourceSections - whether or not this listener should be notified for source sections which were already loaded at the time when this listener was attached.

Returns:

a binding handle to attach and stop the notification stream

Since:

21.1

See Also:

LoadSourceSectionListener.onLoad(LoadSourceSectionEvent)

createLoadSourceSectionBinding

public abstract <T extends LoadSourceSectionListener> EventBinding<T> createLoadSourceSectionBinding(NearestSectionFilter nearestFilter,
                                                                                                     SourceSectionFilter baseFilter,
                                                                                                     T listener,
                                                                                                     boolean includeExistingSourceSections)

Create a binding to get notification for the nearest source section to the given position as specified by the NearestSectionFilter. The final nearest node is selected from the sections filtered by the baseFilter by applying InstrumentableNode.findNearestNodeAt(int, int, Set). The binding needs to be attached to receive notifications. Only subsequent loads will be notified after attach, unless includeExistingSourceSections is true, in which case a notification for each previously loaded source section will be delivered before attach method returns.

The difference from Instrumenter.attachLoadSourceSectionListener(NearestSectionFilter, SourceSectionFilter, LoadSourceSectionListener, boolean) is in having the binding object before notifications are produced when existing source sections are requested.

Parameters:

nearestFilter - a filter describing the nearest section

baseFilter - a filter selecting sections we find the nearest from

listener - a listener that gets notified if a source section was loaded

includeExistingSourceSections - whether or not this listener should be notified for source sections which were already loaded at the time when this listener was attached.

Returns:

a binding handle to attach and stop the notification stream

Since:

23.0

See Also:

LoadSourceSectionListener.onLoad(LoadSourceSectionEvent)

visitLoadedSourceSections

public abstract void visitLoadedSourceSections(SourceSectionFilter filter,
                                               LoadSourceSectionListener listener)

Notifies the listener for each SourceSection in every loaded Source that corresponds to the filter. Only loaded sections are notified, synchronously.

Parameters:

filter - a filter on which source sections trigger events

listener - a listener that gets notified with loaded source sections

Since:

19.0

See Also:

LoadSourceSectionListener.onLoad(LoadSourceSectionEvent)

attachOutConsumer

public abstract <T extends OutputStream> EventBinding<T> attachOutConsumer(T stream)

Attach an output stream as a consumer of the standard output. The consumer output stream receives all output that goes to TruffleInstrument.Env.out() since this call, including output emitted by the Engine this instrumenter is being executed in, output from instruments (including this one), etc. Be sure to dispose the binding when it's not used any more.

Since:

0.25

attachErrConsumer

public abstract <T extends OutputStream> EventBinding<T> attachErrConsumer(T stream)

Attach an output stream as a consumer of the error output . The consumer output stream receives all error output that goes to TruffleInstrument.Env.err() since this call, including error output emitted by the Engine this instrumenter is being executed in, error output from instruments (including this one), etc. Be sure to dispose the binding when it's not used any more.

Since:

0.25

attachAllocationListener

public abstract <T extends AllocationListener> EventBinding<T> attachAllocationListener(AllocationEventFilter filter,
                                                                                        T listener)

Attach a listener to be notified about allocations of guest language values. Be sure to dispose the binding when it's not used any more.

Since:

0.27

attachContextsListener

public abstract <T extends ContextsListener> EventBinding<T> attachContextsListener(T listener,
                                                                                    boolean includeActiveContexts)

Attach a listener to be notified about changes in contexts in guest language application. This is supported in TruffleInstrument.Env.getInstrumenter() only.

Parameters:

listener - a listener to receive the context events

includeActiveContexts - whether or not this listener should be notified for present active contexts

Returns:

a handle for unregistering the listener

Since:

0.30

attachThreadsListener

public abstract <T extends ThreadsListener> EventBinding<T> attachThreadsListener(T listener,
                                                                                  boolean includeInitializedThreads)

Attach a listener to be notified about changes in threads in guest language application. This is supported in TruffleInstrument.Env.getInstrumenter() only.

Parameters:

listener - a listener to receive the context events

includeInitializedThreads - whether or not this listener should be notified for present initialized threads

Returns:

a handle for unregistering the listener

Since:

0.30

attachThreadsActivationListener

public abstract EventBinding<? extends ThreadsActivationListener> attachThreadsActivationListener(ThreadsActivationListener listener)

Attach a listener to be notified about when a thread gets entered or left in guest language applications.

The event notification starts after the listener registration is completed. This means that currently activated threads won't get a notification. It is also possible that ThreadsActivationListener.onLeaveThread(TruffleContext) is called without ever invoking ThreadsActivationListener.onEnterThread(TruffleContext).

Returns:

a handle for unregistering the listener.

Since:

20.3

querySourceSections

public final List<SourceSection> querySourceSections(SourceSectionFilter filter)

Returns a filtered list of loaded SourceSection instances.

Parameters:

filter - criterion for inclusion

Returns:

unmodifiable list of instances that pass the filter

Since:

0.18

queryTags

public abstract Set<Class<?>> queryTags(Node node)

Returns an unmodifiable Set of tag classes which where associated with this node. If the instrumenter is used as a TruffleLanguage then only nodes can be queried for tags that are associated with the current language otherwise an IllegalArgumentException is thrown. The given node must not be null. If the given node is not instrumentable, the given node is not yet adopted by a RootNode or the given tag was not provided by the language then always an empty Set is returned.

Parameters:

node - the node to query

Returns:

an unmodifiable Set of tag classes which where associated with this node.

Since:

0.12

lookupExecutionEventNode

public abstract ExecutionEventNode lookupExecutionEventNode(Node node,
                                                            EventBinding<?> binding)

Returns the execution event node that was inserted at the node's location given an event binding, if any. This is useful to identify and find information from nodes that were created for a specific instrumentation.

Parameters:

node - an instrumentable node specifying the location

binding - the binding to lookup the execution nodes of

Returns:

the ExecutionEventNode, or null.

Since:

19.0