Package com.oracle.truffle.api.instrument

Class Probe

  • All Implemented Interfaces:
    SyntaxTagged
    public final class Probe
extends java.lang.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:
    Instrument, ProbeNode.Instrumentable, ASTProber

    • Method Detail

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

      • findProbesTaggedAs

        public static java.util.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 java.lang.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:
        java.lang.IllegalStateException - if a trap is currently set.

      • clearTagTrap

        public static void clearTagTrap()
        Clears the current SyntaxTagTrap.
        Throws:
        java.lang.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 java.util.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,
                  java.lang.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 java.lang.IllegalStateException
        Adds instrumentation at this Probe.
        Parameters:
        instrument - an instrument not yet attached to a probe
        Throws:
        java.lang.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 java.lang.String getShortDescription()