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 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 `SyntaxTag`s, 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`

### Nested Class Summary

Nested Classes
`static interface` `Probe.ProbeListener` An observer of events related to `Probe`s: creating and tagging.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`static void` `addProbeListener​(Probe.ProbeListener listener)` Adds a `Probe.ProbeListener` to receive events.
`static void` `applyASTProbers​(Node node)` Enables instrumentation in a newly created AST by applying all registered instances of `ASTProber`.
`void` `attach​(Instrument instrument)` Adds instrumentation at this Probe.
`static void` `clearTagTrap()` Clears the current `SyntaxTagTrap`.
`static java.util.Collection<Probe>` `findProbesTaggedAs​(SyntaxTag tag)` Returns all `Probe`s holding a particular `SyntaxTag`, or the whole collection if the specified tag is `null`.
`SourceSection` `getProbedSourceSection()` Gets the `SourceSection` associated with the Guest Language AST node being instrumented, possibly `null`.
`java.lang.String` `getShortDescription()`
`java.util.Collection<SyntaxTag>` `getSyntaxTags()` In which user-sensible categories has this node been tagged (empty set if none).
`boolean` `isTaggedAs​(SyntaxTag tag)` Is this node tagged as belonging to a particular human-sensible category of language constructs?
`static void` `registerASTProber​(ASTProber prober)` Enables instrumentation at selected nodes in all subsequently constructed ASTs.
`static void` `removeProbeListener​(Probe.ProbeListener listener)` Removes a `Probe.ProbeListener`.
`static void` `setTagTrap​(SyntaxTagTrap newTagTrap)` Sets the current "tag trap".
`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.
`static void` `unregisterASTProber​(ASTProber prober)`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

#### 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 java.util.Collection<Probe> findProbesTaggedAs​(SyntaxTag tag)

Returns all `Probe`s 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()