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. aNode
) 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 implementProbeNode.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 viaregisterASTProber(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 Modifier and Type Class Description static interface
Probe.ProbeListener
An observer of events related toProbe
s: creating and tagging.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static void
addProbeListener(Probe.ProbeListener listener)
Adds aProbe.ProbeListener
to receive events.static void
applyASTProbers(Node node)
Enables instrumentation in a newly created AST by applying all registered instances ofASTProber
.void
attach(Instrument instrument)
Adds instrumentation at this Probe.static void
clearTagTrap()
Clears the currentSyntaxTagTrap
.static java.util.Collection<Probe>
findProbesTaggedAs(SyntaxTag tag)
SourceSection
getProbedSourceSection()
Gets theSourceSection
associated with the Guest Language AST node being instrumented, possiblynull
.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 aProbe.ProbeListener
.static void
setTagTrap(SyntaxTagTrap newTagTrap)
Sets the current "tag trap".void
tagAs(SyntaxTag tag, java.lang.Object tagValue)
static void
unregisterASTProber(ASTProber prober)
-
-
-
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 ofASTProber
.
-
addProbeListener
public static void addProbeListener(Probe.ProbeListener listener)
Adds aProbe.ProbeListener
to receive events.
-
removeProbeListener
public static void removeProbeListener(Probe.ProbeListener listener)
Removes aProbe.ProbeListener
. Ignored if listener not found.
-
findProbesTaggedAs
public static java.util.Collection<Probe> findProbesTaggedAs(SyntaxTag tag)
Returns allProbe
s holding a particularSyntaxTag
, or the whole collection if the specified tag isnull
.- 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 aProbe
(either existing or subsequently created) with the specified tag. There can only be one tag trap set at a time.- Parameters:
newTagTrap
- TheSyntaxTagTrap
to set.- Throws:
java.lang.IllegalStateException
- if a trap is currently set.
-
clearTagTrap
public static void clearTagTrap()
Clears the currentSyntaxTagTrap
.- 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 interfaceSyntaxTagged
-
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 interfaceSyntaxTagged
-
tagAs
public void tagAs(SyntaxTag tag, java.lang.Object tagValue)
-
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 theSourceSection
associated with the Guest Language AST node being instrumented, possiblynull
.
-
getShortDescription
public java.lang.String getShortDescription()
-
-