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.

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:

@TruffleInstrument.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(StandardTags.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() {
                @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
`protected static interface`	`TruffleInstrument.ContextLocalFactory<T>` Context local factory for Truffle instruments.
`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.Provider` Used to register a `TruffleInstrument` using a `ServiceLoader`.
`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.

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

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected <T> ContextLocal<T>`	`createContextLocal(TruffleInstrument.ContextLocalFactory<T> factory)` Creates a new context local reference for this instrument.
`protected <T> ContextThreadLocal<T>`	`createContextThreadLocal(TruffleInstrument.ContextThreadLocalFactory<T> factory)` Creates a new context thread local reference for this Truffle language.
`protected org.graalvm.options.OptionDescriptors`	`getContextOptionDescriptors()` Returns a set of option descriptors for instrument options that can be specified per context.
`protected org.graalvm.options.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)` Invoked once on an instance when it becomes disabled, possibly because the underlying engine has been closed.
`protected void`	`onFinalize(TruffleInstrument.Env env)` 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.

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;
        }

    }
}
```
    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:
    
    TruffleInstrument.Env.getInstrumenter()
  - onFinalize
```
protected void onFinalize(TruffleInstrument.Env env)
```
    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 before 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.
    
    Parameters:
    
    env - environment information for the instrument
    
    Since:
    
    19.0
  - onDispose
```
protected void onDispose(TruffleInstrument.Env env)
```
    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.
    
    Parameters:
    
    env - environment information for the instrument
    
    Since:
    
    0.12
  - getOptionDescriptors
```
protected org.graalvm.options.OptionDescriptors getOptionDescriptors()
```
    Returns a set of option descriptors that are supported by this instrument. Option values are accessible using the 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).
    
    Since:
    
    0.27
    
    See Also:
    
    For an example of declaring the option descriptor using an annotation.
  - getContextOptionDescriptors
```
protected org.graalvm.options.OptionDescriptors 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 TruffleInstruement {

   static final OptionDescriptors CONTEXT_OPTIONS = new MyContextOptionDescriptors();

   //...

   protected OptionDescriptors getContextOptionDescriptors() {
      return CONTEXT_OPTIONS;
   }
 }
 
```
    Since:
    
    20.3
    
    See Also:
    
    to lookup the option values for a context.
  - createContextLocal
```
protected final <T> ContextLocal<T> createContextLocal(TruffleInstrument.ContextLocalFactory<T> factory)
```
    Creates a new context local reference for this instrument. Context locals for instruments allow to store additional top-level values for each context similar to language contexts. This enables instruments to use context local values just as languages using their language context. Context local factories are guaranteed to be invoked after the instrument is created.
    Context local references must be created during the invocation in the TruffleInstrument constructor. Calling this method at a later point in time will throw an IllegalStateException. For each registered TruffleInstrument subclass it is required to always produce the same number of context local references. The values produced by the factory must not be null and use a stable exact value type for each instance of a registered instrument class. If the return value of the factory is not stable or null then an IllegalStateException is thrown. These restrictions allow the Truffle runtime to read the value more efficiently.
    Usage example:
```
 @TruffleInstrument.Registration(id = "example", name = "Example Instrument")
 public static class ExampleInstrument extends TruffleInstrument {

     final ContextLocal local = createContextLocal(ExampleLocal::new);

     @Override
     protected void onCreate(Env env) {
         ExecutionEventListener listener = new ExecutionEventListener() {
             public void onEnter(EventContext context, VirtualFrame frame) {
                 ExampleLocal value = local.get();
                 // use context local value;
             }

             public void onReturnValue(EventContext context, VirtualFrame frame, Object result) {
             }

             public void onReturnExceptional(EventContext context, VirtualFrame frame, Throwable exception) {
             }
         };

         env.getInstrumenter().attachExecutionEventListener(
                         SourceSectionFilter.ANY,
                         listener);
     }

     static class ExampleLocal {

         final TruffleContext context;

         ExampleLocal(TruffleContext context) {
             this.context = context;
         }

     }

 }
 
```
    Since:
    
    20.3
  - createContextThreadLocal
```
protected final <T> ContextThreadLocal<T> createContextThreadLocal(TruffleInstrument.ContextThreadLocalFactory<T> factory)
```
    Creates a new context thread local reference for this Truffle language. Context thread locals for languages allow to store additional top-level values for each context and thread. The factory may be invoked on any thread other than the thread of the context thread local value. Context thread local factories are guaranteed to be invoked after the instrument is created.
    Context thread local references must be created during the invocation in the TruffleLanguage constructor. Calling this method at a later point in time will throw an IllegalStateException. For each registered TruffleLanguage subclass it is required to always produce the same number of context thread local references. The values produces by the factory must not be null and use a stable exact value type for each instance of a registered language class. If the return value of the factory is not stable or null then an IllegalStateException is thrown. These restrictions allow the Truffle runtime to read the value more efficiently.
    Context thread locals should not contain a strong reference to the provided thread. Use a weak reference instance for that purpose.
    Usage example:
```
 @TruffleInstrument.Registration(id = "example", name = "Example Instrument")
 public static class ExampleInstrument extends TruffleInstrument {

     final ContextThreadLocal local = createContextThreadLocal(ExampleLocal::new);

     @Override
     protected void onCreate(Env env) {
         ExecutionEventListener listener = new ExecutionEventListener() {
             public void onEnter(EventContext context, VirtualFrame frame) {
                 ExampleLocal value = local.get();
                 // use thread local value;
                 assert value.thread.get() == Thread.currentThread();
             }

             public void onReturnValue(EventContext context, VirtualFrame frame, Object result) {
             }

             public void onReturnExceptional(EventContext context, VirtualFrame frame, Throwable exception) {
             }
         };

         env.getInstrumenter().attachExecutionEventListener(
                         SourceSectionFilter.ANY,
                         listener);
     }

     static class ExampleLocal {

         final TruffleContext context;
         final WeakReference thread;

         ExampleLocal(TruffleContext context, Thread thread) {
             this.context = context;
             this.thread = new WeakReference<>(thread);
         }
     }

 }
 
```
    Since:
    
    20.3

Class TruffleInstrument

Example for a simple expression coverage instrument:

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TruffleInstrument

Method Detail

onCreate

onFinalize

onDispose

getOptionDescriptors

getContextOptionDescriptors

createContextLocal

createContextThreadLocal