com.oracle.truffle.api.instrumentation

Class Instrumenter

java.lang.Object

com.oracle.truffle.api.instrumentation.Instrumenter

public abstract class Instrumenter
extends Object

Provides the capabilities to attach ExecutionEventNodeFactory and ExecutionEventListener instances for a set of source locations specified by a SourceSectionFilter. The result of an attachment is a binding.

Since:

0.12

See Also:

Instrumenter.attachFactory(SourceSectionFilter, ExecutionEventNodeFactory), Instrumenter.attachListener(SourceSectionFilter, ExecutionEventListener)

Method Summary

Modifier and Type	Method and Description
abstract <T extends OutputStream> EventBinding<T>	attachErrConsumer(T stream) Attach an output stream as a consumer of the error output .
abstract <T extends ExecutionEventNodeFactory> EventBinding<T>	attachFactory(SourceSectionFilter filter, T factory) Starts event notification for a given factory and returns a binding which represents a handle to dispose the notification.
abstract <T extends ExecutionEventListener> EventBinding<T>	attachListener(SourceSectionFilter filter, T listener) Starts event notification for a given listener and returns a binding which represents a handle to dispose the notification.
abstract <T extends LoadSourceListener> EventBinding<T>	attachLoadSourceListener(SourceSectionFilter 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(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.
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.

Methods inherited from class java.lang.Object

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

Method Detail

attachFactory

public abstract <T extends ExecutionEventNodeFactory> EventBinding<T> attachFactory(SourceSectionFilter filter,
                                                                                    T factory)

Starts event notification for a given factory and returns a binding which represents a handle to dispose the notification.

Since:

0.12

attachListener

public abstract <T extends ExecutionEventListener> EventBinding<T> attachListener(SourceSectionFilter filter,
                                                                                  T listener)

Starts event notification for a given listener and returns a binding which represents a handle to dispose the notification.

Since:

0.12

attachLoadSourceListener

public abstract <T extends LoadSourceListener> EventBinding<T> attachLoadSourceListener(SourceSectionFilter 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.

Note: the provided SourceSectionFilter must only contain filters on sources or mime types.

Parameters:

filter - a filter on which sources trigger events. Only filters are allowed.

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.15

See Also:

LoadSourceListener.onLoad(LoadSourceEvent)

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.

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)

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 PolyglotEngine 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 PolyglotEngine 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

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