com.oracle.truffle.api.instrumentation

Class TruffleInstrument

java.lang.Object

com.oracle.truffle.api.instrumentation.TruffleInstrument

public abstract class TruffleInstrument
extends Object

The service provider interface (SPI) for Truffle Instruments: clients of Truffle instrumentation that may observe and inject behavior into interpreters written using the Truffle framework.

Each registered instrument can be enabled/disabled multiple times during the lifetime of a PolyglotEngine, but there is never more than one instance per engine. A new TruffleInstrument instance is created each time the instrument is enabled, and the currently enabled instance is disposed when the instrument is disabled.

Registration

Instrument implementation classes must use the TruffleInstrument.Registration annotation to provide required metadata and to enable automatic discovery of the implementation.

Instrument Creation

• When an instrument becomes enabled, a new instance is created and notified once via TruffleInstrument.onCreate(Env).
• 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.

Instrument Disposal

• When an instrument becomes disabled, the current instance is notified once via TruffleInstrument.onDispose(Env).
• 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.
• All enabled instruments in an engine become disabled automatically when the engine is disposed.

Example for a simple expression coverage instrument:

@TruffleInstrument.Registration(id = CoverageExample.ID)
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(EXPRESSION).build();
        Instrumenter instrumenter = env.getInstrumenter();
        instrumenter.attachFactory(filter, new CoverageEventFactory(env));
    }

    private class CoverageEventFactory implements ExecutionEventNodeFactory {

        private final Env env;

        CoverageEventFactory(final Env env) {
            this.env = env;
        }

        public ExecutionEventNode create(final EventContext ec) {
            final PrintStream out = new PrintStream(env.out());
            return new ExecutionEventNode() {
                @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);
                    }
                }
            };
        }
    }

}

Since:

0.12

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TruffleInstrument() Constructor for subclasses.

Method Summary

Modifier and Type	Method and Description
protected abstract void	onCreate(TruffleInstrument.Env env) Invoked once on each newly allocated TruffleInstrument instance.
protected void	onDispose(TruffleInstrument.Env env) Invoked once on an instance when it becomes disabled , possibly because the underlying engine has been disposed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TruffleInstrument

protected TruffleInstrument()

Constructor for subclasses.

Since:

0.12

Method Detail

onCreate

protected abstract void onCreate(TruffleInstrument.Env env)

Invoked once on each newly allocated 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 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;
        }

    }
}

Parameters:

env - environment information for the instrument

Since:

0.12

See Also:

TruffleInstrument.Env.getInstrumenter()

onDispose

protected void onDispose(TruffleInstrument.Env env)

Invoked once on an instance when it becomes disabled , possibly because the underlying engine has been disposed. A disposed instance is no longer usable. If the instrument is re-enabled, the engine will create a new instance.

Parameters:

env - environment information for the instrument

Since:

0.12