Package com.oracle.truffle.api.instrument

Class Probe

java.lang.Object
com.oracle.truffle.api.instrument.Probe
All Implemented Interfaces:
SyntaxTagged
public final class Probe extends Object implements SyntaxTagged
A binding between a particular location in the Truffle AST representation of a running Guest Language (GL) program (i.e. a Node) and a dynamically managed collection of "attached" instrumentation for use by external tools.

The effect of a binding is to intercept execution events at the node and notify each attached Instrument before execution is allowed to resume.

A Probe is "inserted" into a GL node via a call to ProbeNode.Instrumentable.probe(); a GL node must implement ProbeNode.Instrumentable in order to support instrumentation. No more than one Probe can be inserted at a node.

The "probing" of a Truffle AST must be done after it is complete (i.e. with parent pointers correctly assigned), but before any executions. This is done by creating an instance of ASTProber and registering it via registerASTProber(ASTProber), after which it will be automatically applied to newly created ASTs.

Each Probe may also have assigned to it one or more SyntaxTags, for example identifying a node as a STATEMENT. Tags can be queried by tools to configure behavior relevant to each probed node.

Instrumentation is implemented by modifying ASTs, both by inserting nodes into each AST at probed locations and by attaching additional nodes that implement dynamically attached instruments. Attached instrumentation code become, in effect, part of the GL program, and is subject to the same levels of optimization as other GL code. This implementation accounts properly for the fact that Truffle frequently clones ASTs, along with any attached instrumentation nodes. A Probe, along with attached Instruments, represents a logical binding with a source code location, producing event notifications that are (mostly) independent of which AST clone is executing.

See Also:

  • Method Details

    • registerASTProber

      public static void registerASTProber(ASTProber prober)
      Enables instrumentation at selected nodes in all subsequently constructed ASTs.

    • unregisterASTProber

      public static void unregisterASTProber(ASTProber prober)

    • applyASTProbers

      public static void applyASTProbers(Node node)
      Enables instrumentation in a newly created AST by applying all registered instances of ASTProber.

    • addProbeListener

      public static void addProbeListener(Probe.ProbeListener listener)
      Adds a Probe.ProbeListener to receive events.

    • removeProbeListener

      public static void removeProbeListener(Probe.ProbeListener listener)
      Removes a Probe.ProbeListener. Ignored if listener not found.

    • findProbesTaggedAs

      public static Collection<Probe> findProbesTaggedAs(SyntaxTag tag)
      Returns all Probes holding a particular SyntaxTag, or the whole collection if the specified tag is null.
      Returns:
      A collection of probes containing the given tag.

    • setTagTrap

      public static void setTagTrap(SyntaxTagTrap newTagTrap) throws IllegalStateException
      Sets the current "tag trap". This causes a callback to be triggered whenever execution reaches a Probe (either existing or subsequently created) with the specified tag. There can only be one tag trap set at a time.
      Parameters:
      newTagTrap - The SyntaxTagTrap to set.
      Throws:
      IllegalStateException - if a trap is currently set.

    • clearTagTrap

      public static void clearTagTrap()
      Clears the current SyntaxTagTrap.
      Throws:
      IllegalStateException - if no trap is currently set.

    • isTaggedAs

      public boolean isTaggedAs(SyntaxTag tag)
      Description copied from interface: SyntaxTagged
      Is this node tagged as belonging to a particular human-sensible category of language constructs?
      Specified by:
      isTaggedAs in interface SyntaxTagged

    • getSyntaxTags

      public Collection<SyntaxTag> getSyntaxTags()
      Description copied from interface: SyntaxTagged
      In which user-sensible categories has this node been tagged (empty set if none).
      Specified by:
      getSyntaxTags in interface SyntaxTagged

    • tagAs

      public void tagAs(SyntaxTag tag, Object tagValue)
      Adds a tag to the set of tags associated with this Probe; no-op if already in the set.

    • attach

      public void attach(Instrument instrument) throws IllegalStateException
      Adds instrumentation at this Probe.
      Parameters:
      instrument - an instrument not yet attached to a probe
      Throws:
      IllegalStateException - if the instrument has ever been attached before

    • getProbedSourceSection

      public SourceSection getProbedSourceSection()
      Gets the SourceSection associated with the Guest Language AST node being instrumented, possibly null.

    • getShortDescription

      public String getShortDescription()