Class TruffleInstrument
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.
Example for a simple expression coverage instrument:
@Registration(id = CoverageExample.ID, services = Object.class)
public final class CoverageExample extends TruffleInstrument {
public static final String ID = "test-coverage";
private final Set<SourceSection> coverage = new HashSet<>();
@Override
protected void onCreate(final Env env) {
SourceSectionFilter.Builder builder = SourceSectionFilter.newBuilder();
SourceSectionFilter filter = builder.tagIs(ExpressionTag.class).build();
Instrumenter instrumenter = env.getInstrumenter();
instrumenter.attachExecutionEventFactory(filter,
new CoverageExampleEventFactory(env));
}
private class CoverageExampleEventFactory
implements ExecutionEventNodeFactory {
private final Env env;
CoverageExampleEventFactory(final Env env) {
this.env = env;
}
public ExecutionEventNode create(final EventContext ec) {
final PrintStream out = new PrintStream(env.out());
return new ExecutionEventNode() {
@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);
}
}
};
}
}
}
- Since:
- 0.12
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static interface
Context local factory for Truffle instruments.protected static final class
Provider for creating context local and context thread local references.protected static interface
Context local factory for Truffle instruments.static final class
Access to instrumentation services as well as input, output, and error streams.static @interface
Annotation that registers aninstrument
implementations for automatic discovery. -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final TruffleInstrument.ContextLocalProvider
Provider for creating context local and context thread local references. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected final <T> ContextLocal
<T> Deprecated.protected final <T> ContextThreadLocal
<T> Deprecated.protected OptionDescriptors
Returns a set of option descriptors for instrument options that can be specified per context.protected OptionDescriptors
Returns a set of option descriptors that are supported by this instrument.protected OptionDescriptors
Returns a set of source option descriptors that are supported by this language.protected abstract void
Invoked once on each newly allocatedTruffleInstrument
instance.protected void
protected void
-
Field Details
-
locals
Provider for creating context local and context thread local references.- Since:
- 23.1
- See Also:
-
-
Constructor Details
-
TruffleInstrument
protected TruffleInstrument()Constructor for subclasses.- Since:
- 0.12
-
-
Method Details
-
onCreate
Invoked once on each newly allocatedTruffleInstrument
instance.The method may
register
additionalservices
- e.g. objects to be exposed vialookup 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); } }
service
associated with the instrument, implement it, instantiate andregister
in own's instrumentonCreate
method:@Registration(id = DebuggerExample.ID, services = DebuggerController.class) public final class DebuggerExample extends TruffleInstrument { 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 final Instrumenter instrumenter; private EventBinding<?> 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.- Parameters:
env
- environment information for the instrument- Since:
- 0.12
- See Also:
-
onFinalize
Invoked once on an instance just before all instruments and languages are going to be disposed, possibly because the underlying engine is going to be closed. This method is called beforeonDispose(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,onDispose(Env)
for active instruments on unclosedengines
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.- Parameters:
env
- environment information for the instrument- Since:
- 19.0
-
onDispose
Invoked once on an instance when it becomes disabled, possibly because the underlying engine has been closed. A disposed instance is no longer usable. If the instrument is re-enabled, the engine will create a new instance. In the event of VM shutdown, this method is not called for active instruments on unclosedengines
. The unclosed engines are not closed automatically on VM shutdown, they just die with the VM.- Parameters:
env
- environment information for the instrument- Since:
- 0.12
-
getOptionDescriptors
Returns a set of option descriptors that are supported by this instrument. Option values are accessible using theenvironment
when the instrument iscreated
. By default no options are available for an instrument. Options returned by this method must specify theinstrument id
asname
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 becreated
if one of the specified options was provided by the engine. To construct option descriptors from a list thenOptionDescriptors.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
getContextOptionDescriptors()
and the values can be accessed withTruffleInstrument.Env.getOptions(TruffleContext)
.- Since:
- 0.27
- See Also:
-
getContextOptionDescriptors
Returns a set of option descriptors for instrument options that can be specified per context. This can be specified in addition to options specified on the engine level, instruments may specify options for each context. Option descriptors specified per context must not overlap with option descriptors specified per instrument instance.Example usage:
@Option.Group(MyInstrument.ID) final class MyContext { @Option(category = OptionCategory.EXPERT, help = "Description...") static final OptionKey
MyContextOption = new OptionKey<>(Boolean.FALSE); } @Registration(...) class MyInstrument extends TruffleInstrument { static final OptionDescriptors CONTEXT_OPTIONS = new MyContextOptionDescriptors(); //... protected OptionDescriptors getContextOptionDescriptors() { return CONTEXT_OPTIONS; } } - Since:
- 20.3
- See Also:
-
getSourceOptionDescriptors
Returns a set of source option descriptors that are supported by this language. Option values are accessible using theenvironment
. Languages must always return the same option descriptors independent of the language instance or side-effects.- Since:
- 25.0
- See Also:
-
createContextLocal
@Deprecated protected final <T> ContextLocal<T> createContextLocal(TruffleInstrument.ContextLocalFactory<T> factory) Deprecated.Creates a new context local reference for this Truffle instrument. Starting with JDK 21, using this method leads to a this-escape warning. UseTruffleInstrument.ContextLocalProvider.createContextLocal(TruffleInstrument.ContextLocalFactory)
instead.- Since:
- 20.3
-
createContextThreadLocal
@Deprecated protected final <T> ContextThreadLocal<T> createContextThreadLocal(TruffleInstrument.ContextThreadLocalFactory<T> factory) Deprecated.Creates a new context thread local reference for this Truffle instrument. Starting with JDK 21, using this method leads to a this-escape warning. UseTruffleInstrument.ContextLocalProvider.createContextThreadLocal(TruffleInstrument.ContextThreadLocalFactory)
instead.- Since:
- 20.3
-
TruffleInstrument.ContextLocalProvider.createContextLocal(TruffleInstrument.ContextLocalFactory)
instead