Package com.oracle.truffle.api.instrument

## 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 `Instrument`s.

Disclaimer: experimental interface under development.

See Also:
  `Instrument`

### Method Summary

All Methods Instance Methods Abstract Methods
`Node` `getChild()` Gets the node being "wrapped", i.e.
`Probe` `getProbe()` Gets the `Probe` responsible for installing this wrapper; none if the wrapper installed via "lite-Probing".
`void` `insertProbe​(ProbeNode probeNode)` Implementation support for completing a newly created wrapper node.

### Methods inherited from interface com.oracle.truffle.api.instrument.InstrumentationNode

`instrumentationInfo`

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