Interface ProbeNode.WrapperNode

  • All Superinterfaces:
    InstrumentationNode
    Enclosing class:
    ProbeNode

    public static interface ProbeNode.WrapperNode
    extends InstrumentationNode
    A node that can be inserted into a Truffle AST, and which enables instrumentation at a particular Guest Language (GL) node.

    The implementation must be GL-specific. A wrapper decorates a GL AST node (the wrapper's child) by acting as a transparent proxy with respect to the GL's execution semantics.

    Instrumentation at the wrapped node is implemented by an instance of ProbeNode attached as a second child of the ProbeNode.WrapperNode.

    A wrapper is obliged to notify its attached ProbeNode when execution events occur at the wrapped AST node during program execution.

    When a GL AST is cloned, the ProbeNode.WrapperNode, its ProbeNode and any instrumentation are also cloned; they are in effect part of the GL AST. An instance of Probe represents abstractly the instrumentation at a particular location in a GL AST; it tracks all the copies of the Wrapper and attached instrumentation, and acts as a single point of access for tools.

    This interface is not intended to be visible as part of the API for tools (instrumentation clients).

    Implementation guidelines:

    1. Each GL implementation should include a WrapperNode implementation; usually only one is needed.
    2. The wrapper type should descend from the GL-specific node class.
    3. Must have a field: @Child private <GL>Node child;
    4. Must have a field: @Child private ProbeNode probeNode;
    5. The wrapper must act as a proxy for its child, which means implementing every possible execute- method that gets called on guest language AST node types by their parents, and passing along each call to its child.
    6. Method Probe getProbe() should be implemented as probeNode.getProbe();
    7. Method insertProbe(ProbeNode) should be implemented as this.probeNode=insert(newProbeNode);
    8. Most importantly, Wrappers must be implemented so that Truffle optimization will reduce their runtime overhead to zero when there are no attached Instruments.

    Disclaimer: experimental interface under development.

    See Also:
    Instrument
    • Method Detail

      • getChild

        Node getChild()
        Gets the node being "wrapped", i.e. the AST node for which execution events will be reported through the Instrumentation Framework.
      • getProbe

        Probe getProbe()
        Gets the Probe responsible for installing this wrapper; none if the wrapper installed via "lite-Probing".
      • insertProbe

        void insertProbe​(ProbeNode probeNode)
        Implementation support for completing a newly created wrapper node.