public final class Probe extends java.lang.Object implements SyntaxTagged
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.
Instrument
,
ProbeNode.Instrumentable
,
ASTProber
Modifier and Type | Class and Description |
---|---|
static interface |
Probe.ProbeListener
An observer of events related to
Probe s: creating and tagging. |
Modifier and Type | Method and Description |
---|---|
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)
|
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)
|
static void |
unregisterASTProber(ASTProber prober) |
public static void registerASTProber(ASTProber prober)
public static void unregisterASTProber(ASTProber prober)
public static void applyASTProbers(Node node)
ASTProber
.public static void addProbeListener(Probe.ProbeListener listener)
Probe.ProbeListener
to receive events.public static void removeProbeListener(Probe.ProbeListener listener)
Probe.ProbeListener
. Ignored if listener not found.public static java.util.Collection<Probe> findProbesTaggedAs(SyntaxTag tag)
Probe
s holding a particular SyntaxTag
, or the whole collection if
the specified tag is null
.public static void setTagTrap(SyntaxTagTrap newTagTrap) throws java.lang.IllegalStateException
Probe
(either existing or subsequently created) with the specified tag.
There can only be one tag trap set at a time.newTagTrap
- The SyntaxTagTrap
to set.java.lang.IllegalStateException
- if a trap is currently set.public static void clearTagTrap()
SyntaxTagTrap
.java.lang.IllegalStateException
- if no trap is currently set.public boolean isTaggedAs(SyntaxTag tag)
SyntaxTagged
isTaggedAs
in interface SyntaxTagged
public java.util.Collection<SyntaxTag> getSyntaxTags()
SyntaxTagged
getSyntaxTags
in interface SyntaxTagged
public void tagAs(SyntaxTag tag, java.lang.Object tagValue)
public void attach(Instrument instrument) throws java.lang.IllegalStateException
instrument
- an instrument not yet attached to a probejava.lang.IllegalStateException
- if the instrument has ever been attached beforepublic SourceSection getProbedSourceSection()
SourceSection
associated with the Guest Language AST node being
instrumented, possibly null
.public java.lang.String getShortDescription()