com.oracle.truffle.api.instrumentation

Class TruffleInstrument.ContextLocalProvider

java.lang.Object

com.oracle.truffle.api.instrumentation.TruffleInstrument.ContextLocalProvider

Enclosing class:

TruffleInstrument

protected static final class TruffleInstrument.ContextLocalProvider
extends Object

Provider for creating context local and context thread local references.

Since:

23.1

See Also:

TruffleInstrument.locals, TruffleInstrument.ContextLocalProvider.createContextLocal(TruffleInstrument.ContextLocalFactory), TruffleInstrument.ContextLocalProvider.createContextThreadLocal(TruffleInstrument.ContextThreadLocalFactory)

Method Summary

Modifier and Type	Method and Description
<T> ContextLocal<T>	createContextLocal(TruffleInstrument.ContextLocalFactory<T> factory) Creates a new context local reference for this instrument.
<T> ContextThreadLocal<T>	createContextThreadLocal(TruffleInstrument.ContextThreadLocalFactory<T> factory) Creates a new context thread local reference for this Truffle language.

Methods inherited from class java.lang.Object

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

Method Detail

createContextLocal

public <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 = locals.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:

23.1

createContextThreadLocal

public <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 = locals.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:

23.1