public final class Instrument
extends java.lang.Object
Probe
, which provides notification of
execution events taking place at a Node
in a Guest
Language (GL) Truffle AST, and a receiver, which consumes
notifications on behalf of an external tool.
TruffleEventReceiver
that responds to events on behalf of
a tool.create(TruffleEventReceiver)
.Probe.attach(Instrument)
, at which point event
notifications begin to arrive at the receiver.dispose()
, at which
point event notifications to the receiver cease, and the Instrument becomes unusable.
TruffleEventReceiver
. The event handling methods account for
both the entry into an AST node (about to call) and several possible kinds of exit from an AST
node (just returned).DefaultEventReceiver
, which provides a no-op implementation of every
TruffleEventReceiver
method; override the methods of interest.SimpleEventReceiver
, where return values are ignored so only two methods (for
"enter" and "return") will notify all events.
When an Instrument is attached to a Probe, the receiver effectively becomes part of the executing GL program; performance can be affected by the receiver's implementation.
Frame
or Node
references in fields.final
fields and (where performance is important) short methods.VirtualFrame
reference from an event notification as far as
possible through code that is expected to be inlined, since this incurs no runtime overhead. When
access to frame data is needed, substitute a more expensive materialized representation of the frame.CompilerDirectives.TruffleBoundary
.CompilerDirectives.TruffleBoundary
annotations).
Truffle routinely clones ASTs, which has consequences for receiver implementation.
Probe
is uniquely associated with a particular location in the
executing Guest Language program, execution events at that location will in general be
implemented by different Node
instances, i.e. clones of the originally probed
node.Node
supplied with notifications to a particular
receiver will vary, but because they all represent the same GL program location the events should
be treated as equivalent for most purposes.
Node
: the concrete node (in one of the AST's clones) from which the event originated.
VirtualFrame
: the current execution frame.
final
of course. For example, a reference to the Probe
to which the receiver's
Instrument has been attached would give access to its corresponding
source location or to the collection of
tags currently applied to the Probe.
Instruments are single-use:
Probe.attach(Instrument)
, and it may only be attached to a single Probe. It is a runtime
error to attempt attaching a previously attached instrument.dispose()
makes an instrument inactive by removing it from the
Probe to which it was attached and rendering it permanently inert.
Although an Instrument may only be attached to a single Probe, a receiver can be shared among multiple Instruments. This can be useful for observing events that might happen at different locations in a single AST, for example all assignments to a particular variable. In this case a new Instrument would be created and attached at each assignment node, but all the Instruments would be created with the same receiver.
Disclaimer: experimental; under development.
Probe
,
TruffleEventReceiver
Modifier and Type | Method and Description |
---|---|
static Instrument |
create(TruffleEventReceiver receiver)
Creates an instrument that will route execution events to a receiver.
|
static Instrument |
create(TruffleEventReceiver receiver,
java.lang.String instrumentInfo)
Creates an instrument that will route execution events to a receiver.
|
void |
dispose()
Removes this instrument (and any clones) from the probe to which it attached and renders the
instrument inert.
|
public static Instrument create(TruffleEventReceiver receiver, java.lang.String instrumentInfo)
receiver
- a receiver for event generated by the instrumentinstrumentInfo
- optional description of the instrument's rolepublic static Instrument create(TruffleEventReceiver receiver)
public void dispose() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if this instrument has already been disposed