public abstract class Instrumenter extends Object
Modifier and Type | Method and Description |
---|---|
abstract <T extends AllocationListener> |
attachAllocationListener(AllocationEventFilter filter,
T listener)
Attach a
listener to be notified about allocations of guest
language values. |
abstract <T extends ContextsListener> |
attachContextsListener(T listener,
boolean includeActiveContexts)
Attach a
listener to be notified about changes in contexts in guest
language application. |
abstract <T extends OutputStream> |
attachErrConsumer(T stream)
Attach an output stream as a consumer of the
error output
. |
abstract <T extends ExecuteSourceListener> |
attachExecuteSourceListener(SourceFilter filter,
T listener,
boolean includeExecutedSources)
|
abstract <T extends ExecutionEventNodeFactory> |
attachExecutionEventFactory(NearestSectionFilter nearestFilter,
SourceSectionFilter baseFilter,
T factory)
Starts execution event notification for the nearest
SourceSection as specified by the
NearestSectionFilter . |
abstract <T extends ExecutionEventNodeFactory> |
attachExecutionEventFactory(SourceSectionFilter eventFilter,
SourceSectionFilter inputFilter,
T factory)
Starts execution event notification for a given
event filter and
factory . |
<T extends ExecutionEventNodeFactory> |
attachExecutionEventFactory(SourceSectionFilter eventFilter,
T factory)
Starts execution event notification for a given
event filter and
factory . |
<T extends ExecutionEventListener> |
attachExecutionEventListener(SourceSectionFilter eventFilter,
T listener)
Starts execution event notification for a given
event filter and
listener . |
abstract <T extends LoadSourceListener> |
attachLoadSourceListener(SourceFilter filter,
T listener,
boolean includeExistingSources)
|
abstract <T extends LoadSourceSectionListener> |
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> |
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> |
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> |
attachThreadsListener(T listener,
boolean includeInitializedThreads)
Attach a
listener to be notified about changes in threads in guest
language application. |
abstract <T extends ExecuteSourceListener> |
createExecuteSourceBinding(SourceFilter filter,
T listener,
boolean includeExecutedSources)
|
abstract <T extends LoadSourceListener> |
createLoadSourceBinding(SourceFilter filter,
T listener,
boolean includeExistingSources)
|
abstract <T extends LoadSourceSectionListener> |
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> |
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. |
public final <T extends ExecutionEventListener> EventBinding<T> attachExecutionEventListener(SourceSectionFilter eventFilter, T listener)
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.
eventFilter
- filters the events that are reported to the given
listener
listener
- that listens to execution events.ExecutionEventListener
public final <T extends ExecutionEventNodeFactory> EventBinding<T> attachExecutionEventFactory(SourceSectionFilter eventFilter, T factory)
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.
eventFilter
- filters the events that are reported to the execution event nodes
created by the factory.factory
- the factory that creates execution event nodes
.ExecutionEventNodeFactory
,
Instrumenter.attachExecutionEventFactory(SourceSectionFilter, SourceSectionFilter,
ExecutionEventNodeFactory)
public abstract <T extends ExecutionEventNodeFactory> EventBinding<T> attachExecutionEventFactory(SourceSectionFilter eventFilter, SourceSectionFilter inputFilter, T factory)
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.
eventFilter
- filters the events that are reported to the execution event nodes
created by the factory.inputFilter
- filters input events, null
for no input valuesfactory
- the factory that creates execution event nodes
.ExecutionEventNodeFactory
,
ExecutionEventNode.onInputValue(com.oracle.truffle.api.frame.VirtualFrame, EventContext,
int, Object)
public abstract <T extends ExecutionEventNodeFactory> EventBinding<T> attachExecutionEventFactory(NearestSectionFilter nearestFilter, SourceSectionFilter baseFilter, T factory)
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)
.
nearestFilter
- a filter describing the nearest sectionbaseFilter
- a filter selecting sections we find the nearest fromfactory
- the factory that creates execution event nodes
.ExecutionEventNodeFactory
public abstract <T extends LoadSourceListener> EventBinding<T> attachLoadSourceListener(SourceFilter filter, T listener, boolean includeExistingSources)
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.filter
- a filter on which sources events are triggered.listener
- a listener that gets notified if a source was loadedincludeExistingSources
- whether or not this listener should be notified for sources
which were already loaded at the time when this listener was attached.LoadSourceListener.onLoad(LoadSourceEvent)
public abstract <T extends ExecuteSourceListener> EventBinding<T> attachExecuteSourceListener(SourceFilter filter, T listener, boolean includeExecutedSources)
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 RootNode
s start to be
executed. Every source is reported at most once.filter
- a filter on which source events are triggered.listener
- a listener that gets notified if a source was executedincludeExecutedSources
- whether or not this listener should be notified for sources
which were already executed at the time when this listener was attached.ExecuteSourceListener.onExecute(ExecuteSourceEvent)
public abstract <T extends LoadSourceSectionListener> EventBinding<T> attachLoadSourceSectionListener(SourceSectionFilter filter, T listener, boolean includeExistingSourceSections)
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.filter
- a filter on which sources sections trigger eventslistener
- a listener that gets notified if a source section was loadedincludeExistingSourceSections
- whether or not this listener should be notified for
sources which were already loaded at the time when this listener was attached.LoadSourceSectionListener.onLoad(LoadSourceSectionEvent)
public abstract <T extends LoadSourceSectionListener> EventBinding<T> attachLoadSourceSectionListener(NearestSectionFilter nearestFilter, SourceSectionFilter baseFilter, T listener, boolean includeExistingSourceSections)
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.
nearestFilter
- a filter describing the nearest sectionbaseFilter
- a filter selecting sections we find the nearest fromlistener
- a listener that gets notified if a source section was loadedincludeExistingSourceSections
- whether or not this listener should be notified for
source sections which were already loaded at the time when this listener was
attached.LoadSourceSectionListener.onLoad(LoadSourceSectionEvent)
public abstract <T extends LoadSourceListener> EventBinding<T> createLoadSourceBinding(SourceFilter filter, T listener, boolean includeExistingSources)
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.
filter
- a filter on which sources events are triggered.listener
- a listener that gets notified if a source was loadedincludeExistingSources
- whether or not this listener should be notified for sources
which were already loaded at the time when this listener was attached.attach
and
stop
the notification streamLoadSourceListener.onLoad(LoadSourceEvent)
public abstract <T extends ExecuteSourceListener> EventBinding<T> createExecuteSourceBinding(SourceFilter filter, T listener, boolean includeExecutedSources)
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.
filter
- a filter on which sources events are triggered.listener
- a listener that gets notified if a source was executedincludeExecutedSources
- whether or not this listener should be notified for sources
which were already executed at the time when this listener was attached.attach
and
stop
the notification streamExecuteSourceListener.onExecute(ExecuteSourceEvent)
public abstract <T extends LoadSourceSectionListener> EventBinding<T> createLoadSourceSectionBinding(SourceSectionFilter filter, T listener, boolean includeExistingSourceSections)
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.
filter
- a filter on which sources events are triggered.listener
- a listener that gets notified if a source section was loadedincludeExistingSourceSections
- whether or not this listener should be notified for
source sections which were already loaded at the time when this listener was
attached.attach
and
stop
the notification streamLoadSourceSectionListener.onLoad(LoadSourceSectionEvent)
public abstract <T extends LoadSourceSectionListener> EventBinding<T> createLoadSourceSectionBinding(NearestSectionFilter nearestFilter, SourceSectionFilter baseFilter, T listener, boolean includeExistingSourceSections)
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.
nearestFilter
- a filter describing the nearest sectionbaseFilter
- a filter selecting sections we find the nearest fromlistener
- a listener that gets notified if a source section was loadedincludeExistingSourceSections
- whether or not this listener should be notified for
source sections which were already loaded at the time when this listener was
attached.attach
and
stop
the notification streamLoadSourceSectionListener.onLoad(LoadSourceSectionEvent)
public abstract void visitLoadedSourceSections(SourceSectionFilter filter, LoadSourceSectionListener listener)
SourceSection
in every loaded Source
that
corresponds to the filter. Only loaded sections are notified, synchronously.filter
- a filter on which source sections trigger eventslistener
- a listener that gets notified with loaded source sectionsLoadSourceSectionListener.onLoad(LoadSourceSectionEvent)
public abstract <T extends OutputStream> EventBinding<T> attachOutConsumer(T stream)
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.public abstract <T extends OutputStream> EventBinding<T> attachErrConsumer(T stream)
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.public abstract <T extends AllocationListener> EventBinding<T> attachAllocationListener(AllocationEventFilter filter, T listener)
listener
to be notified about allocations of guest
language values. Be sure to dispose
the binding when it's not
used any more.public abstract <T extends ContextsListener> EventBinding<T> attachContextsListener(T listener, boolean includeActiveContexts)
listener
to be notified about changes in contexts in guest
language application. This is supported in TruffleInstrument.Env.getInstrumenter()
only.listener
- a listener to receive the context eventsincludeActiveContexts
- whether or not this listener should be notified for present
active contextspublic abstract <T extends ThreadsListener> EventBinding<T> attachThreadsListener(T listener, boolean includeInitializedThreads)
listener
to be notified about changes in threads in guest
language application. This is supported in TruffleInstrument.Env.getInstrumenter()
only.listener
- a listener to receive the context eventsincludeInitializedThreads
- whether or not this listener should be notified for present
initialized threadspublic abstract EventBinding<? extends ThreadsActivationListener> attachThreadsActivationListener(ThreadsActivationListener listener)
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)
.
public final List<SourceSection> querySourceSections(SourceSectionFilter filter)
SourceSection
instances.filter
- criterion for inclusionpublic abstract Set<Class<?>> queryTags(Node node)
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.node
- the node to querySet
of tag classes which where associated with this node.public abstract ExecutionEventNode lookupExecutionEventNode(Node node, EventBinding<?> binding)
node
- an instrumentable node specifying the locationbinding
- the binding to lookup the execution nodes ofExecutionEventNode
, or null
.