Class Probe
- All Implemented Interfaces:
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.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
An observer of events related toProbe
s: creating and tagging. -
Method Summary
Modifier and TypeMethodDescriptionstatic 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
Clears the currentSyntaxTagTrap
.static Collection<Probe>
Gets theSourceSection
associated with the Guest Language AST node being instrumented, possiblynull
.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
static void
unregisterASTProber
(ASTProber prober)
-
Method Details
-
registerASTProber
Enables instrumentation at selected nodes in all subsequently constructed ASTs. -
unregisterASTProber
-
applyASTProbers
Enables instrumentation in a newly created AST by applying all registered instances ofASTProber
. -
addProbeListener
Adds aProbe.ProbeListener
to receive events. -
removeProbeListener
Removes aProbe.ProbeListener
. Ignored if listener not found. -
findProbesTaggedAs
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
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:
IllegalStateException
- if a trap is currently set.
-
clearTagTrap
public static void clearTagTrap()Clears the currentSyntaxTagTrap
.- Throws:
IllegalStateException
- if no trap is currently set.
-
isTaggedAs
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
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
-
attach
Adds instrumentation at this Probe.- Parameters:
instrument
- an instrument not yet attached to a probe- Throws:
IllegalStateException
- if the instrument has ever been attached before
-
getProbedSourceSection
Gets theSourceSection
associated with the Guest Language AST node being instrumented, possiblynull
. -
getShortDescription
-