Package 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 Details

    • 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:

    • 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 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:

    • attachExecutionEventListener

      @Deprecated(since="20.0") public abstract <T extends ExecutionEventListener> EventBinding<T> attachExecutionEventListener(SourceSectionFilter eventFilter, SourceSectionFilter inputFilter, T listener)
      Deprecated.
      inputFilters do not work for execution event listeners Use attachExecutionEventFactory(SourceSectionFilter, SourceSectionFilter, ExecutionEventNodeFactory) or use attachExecutionEventListener(SourceSectionFilter, ExecutionEventListener) instead.
      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.

      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 given listener
      inputFilter - filters input events, null for no input values
      listener - that listens to execution events.
      Since:
      0.33
      See Also:

    • 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:

    • 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:

    • attachLoadSourceListener

      @Deprecated(since="19.0") public abstract <T extends LoadSourceListener> EventBinding<T> attachLoadSourceListener(SourceSectionFilter filter, T listener, boolean includeExistingSources)
      Deprecated.
      Use attachLoadSourceListener(SourceFilter, LoadSourceListener, boolean)
      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 source 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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 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:

    • 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 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:

    • 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 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:

    • 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 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:

    • 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:

    • 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