public abstract class TruffleInstrument extends Object
Instrument implementation classes must use the TruffleInstrument.Registration
annotation to provide
required metadata and to enable automatic discovery of the implementation.
An instrument is created
if at least one instrument
option
was specified or if a
service
was looked up. The
Instrumenter
available in the provided environment allows the instrument
instance to bind listeners for execution and
source events, as well as node factories for code injection at guest language code locations.
An instrument is disposed when the associated polyglot engine is disposed.
All active bindings created by a disposed instrument become disposed automatically. The
Instrumenter
instance available in the provided environment may not be
used after disposal.
@TruffleInstrument.Registration
(id = CoverageExample.ID, services =Object
.class) public final class CoverageExample extendsTruffleInstrument
{ public static finalString
ID = "test-coverage"; private finalSet
<SourceSection
> coverage = newHashSet
<>(); @Override
protected void onCreate(final Env env) {SourceSectionFilter
.Builder builder =SourceSectionFilter
.newBuilder();SourceSectionFilter
filter = builder.tagIs(StandardTags.ExpressionTag
.class).build();Instrumenter
instrumenter = env.getInstrumenter(); instrumenter.attachExecutionEventFactory(filter, new CoverageExampleEventFactory(env)); } private class CoverageExampleEventFactory implementsExecutionEventNodeFactory
{ private final Env env; CoverageExampleEventFactory(final Env env) { this.env = env; } publicExecutionEventNode
create(finalEventContext
ec) { finalPrintStream
out = newPrintStream
(env.out()); return newExecutionEventNode
() { @CompilerDirectives.CompilationFinal
private boolean visited; @Override
public void onReturnValue(VirtualFrame
vFrame,Object
result) { if (!visited) {CompilerDirectives
.transferToInterpreterAndInvalidate(); visited = true;SourceSection
src = ec.getInstrumentedSourceSection(); out.print(src.getCharIndex() + " "); coverage.add(src); } } }; } } }
Modifier and Type | Class and Description |
---|---|
protected static interface |
TruffleInstrument.ContextLocalFactory<T>
Context local factory for Truffle instruments.
|
protected static class |
TruffleInstrument.ContextLocalProvider
Provider for creating context local and context thread local references.
|
protected static interface |
TruffleInstrument.ContextThreadLocalFactory<T>
Context local factory for Truffle instruments.
|
static class |
TruffleInstrument.Env
Access to instrumentation services as well as input, output, and error streams.
|
static interface |
TruffleInstrument.Registration
Annotation that registers an
instrument implementations for
automatic discovery. |
Modifier and Type | Field and Description |
---|---|
protected TruffleInstrument.ContextLocalProvider |
locals
Provider for creating context local and context thread local references.
|
Modifier | Constructor and Description |
---|---|
protected |
TruffleInstrument()
Constructor for subclasses.
|
Modifier and Type | Method and Description |
---|---|
protected OptionDescriptors |
getContextOptionDescriptors()
Returns a set of option descriptors for instrument options that can be specified per context.
|
protected OptionDescriptors |
getOptionDescriptors()
Returns a set of option descriptors that are supported by this instrument.
|
protected abstract void |
onCreate(TruffleInstrument.Env env)
Invoked once on each newly allocated
TruffleInstrument instance. |
protected void |
onDispose(TruffleInstrument.Env env)
|
protected void |
onFinalize(TruffleInstrument.Env env)
|
protected final TruffleInstrument.ContextLocalProvider locals
protected TruffleInstrument()
protected abstract void onCreate(TruffleInstrument.Env env)
TruffleInstrument
instance.
The method may register
additional
services
- e.g. objects to be exposed via
lookup query
. For example to expose a debugger
one could define an abstract debugger controller:
public abstract class DebuggerController {
DebuggerController() {
}
public abstract void installBreakpoint(int i, Callback callback);
public abstract void stepInto(Callback callback);
public abstract void stepOut(Callback callback);
public abstract void stepOver(Callback callback);
public interface Callback {
void halted(DebuggerController debugger, EventContext
haltedAt);
}
}
and declare it as a service
associated with the instrument,
implement it, instantiate and register
in own's
instrument onCreate
method:
@TruffleInstrument.Registration
(id = DebuggerExample.ID, services = DebuggerController.class) public final class DebuggerExample extendsTruffleInstrument
{ private Controller controller; @Override
protected void onCreate(Env env) { assert this.controller == null; this.controller = new Controller(env.getInstrumenter()); env.registerService(controller); } private static final class Controller extends DebuggerController { private finalInstrumenter
instrumenter; privateEventBinding
<?> stepping; private Callback currentStatementCallback; Controller(Instrumenter
instrumenter) { this.instrumenter = instrumenter; } } }
If this method throws an AbstractTruffleException
the exception interop messages are executed without a context being entered.
env
- environment information for the instrumentTruffleInstrument.Env.getInstrumenter()
protected void onFinalize(TruffleInstrument.Env env)
TruffleInstrument.onDispose(Env)
and the instrument must remain usable after finalization. The
instrument can prepare for disposal while still having other instruments not disposed yet. In
the event of VM shutdown, TruffleInstrument.onDispose(Env)
for active instruments on unclosed
engines
is not called, and so in case the instrument is
supposed to do some specific action before its disposal, e.g. print some kind of summary, it
should be done in this method.env
- environment information for the instrumentprotected void onDispose(TruffleInstrument.Env env)
engines
. The unclosed engines are
not closed automatically on VM shutdown, they just die with the VM.env
- environment information for the instrumentprotected OptionDescriptors getOptionDescriptors()
environment
when the instrument is
created
. By default no options are available for an instrument.
Options returned by this method must specify the instrument id
as
name
prefix for each option. For example if the id of the
instrument is "debugger" then a valid option name would be "debugger.Enabled". The instrument
will automatically be created
if one of the specified options was
provided by the engine. To construct option descriptors from a list then
OptionDescriptors.create(List)
can be used.
By default option descriptors may only be specified per engine or bound engine, but option
values may also be specified per context. In this case the context specific options can be
specified with TruffleInstrument.getContextOptionDescriptors()
and the values can be accessed with
TruffleInstrument.Env.getOptions(TruffleContext)
.
For an example of declaring the option descriptor using an annotation.
protected OptionDescriptors getContextOptionDescriptors()
Example usage:
@Option.Group(MyInstrument.ID) final class MyContext { @Option(category = OptionCategory.EXPERT, help = "Description...") static final OptionKeyMyContextOption = new OptionKey<>(Boolean.FALSE); } @Registration(...) class MyInstrument extends TruffleInstrument { static final OptionDescriptors CONTEXT_OPTIONS = new MyContextOptionDescriptors(); //... protected OptionDescriptors getContextOptionDescriptors() { return CONTEXT_OPTIONS; } }
to lookup the option values for a context.