com.oracle.truffle.api

Class TruffleLanguage.ContextLocalProvider<C>

java.lang.Object

com.oracle.truffle.api.TruffleLanguage.ContextLocalProvider<C>

Enclosing class:

TruffleLanguage<C>

protected static final class TruffleLanguage.ContextLocalProvider<C>
extends Object

Provider for creating context local and context thread local references.

Since:

23.1

See Also:

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

Method Summary

Modifier and Type	Method and Description
<T> ContextLocal<T>	createContextLocal(TruffleLanguage.ContextLocalFactory<C,T> factory) Creates a new context local reference for this Truffle language.
<T> ContextThreadLocal<T>	createContextThreadLocal(TruffleLanguage.ContextThreadLocalFactory<C,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(TruffleLanguage.ContextLocalFactory<C,T> factory)

Creates a new context local reference for this Truffle language. Context locals for languages allow to store additional top-level values for each context besides the language context. The advantage of context locals compared to storing the value in a field of the language context is that reading a context local requires one indirection less. It is recommended to use context locals for languages only if the read is critical for performance.

Context 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 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 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.

Usage example:

 @TruffleLanguage.Registration(id = "example", name = "ExampleLanguage")
 public final class ExampleLanguage extends TruffleLanguage {

     final ContextLocal contextLocal = locals.createContextLocal(ExampleLocal::new);

     @Override
     protected Env createContext(Env env) {
         return env;
     }

     @Override
     protected CallTarget parse(ParsingRequest request) throws Exception {
         return new RootNode(this) {
             @Override
             public Object execute(VirtualFrame frame) {
                 // fast read
                 ExampleLocal local = contextLocal.get();
                 // access local
                 return "";
             }
         }.getCallTarget();
     }

     static final class ExampleLocal {

         final Env env;

         ExampleLocal(Env env) {
             this.env = env;
         }

     }
 }
 

Since:

23.1

createContextThreadLocal

public <T> ContextThreadLocal<T> createContextThreadLocal(TruffleLanguage.ContextThreadLocalFactory<C,T> factory)

Creates a new context thread local reference for this Truffle language. Context threadlocals for languages allow storing 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 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 produced 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:

 @TruffleLanguage.Registration(id = "example", name = "ExampleLanguage")
 public static class ExampleLanguage extends TruffleLanguage {

     final ContextThreadLocal threadLocal = locals.createContextThreadLocal(ExampleLocal::new);

     @Override
     protected Env createContext(Env env) {
         return env;
     }

     @Override
     protected CallTarget parse(ParsingRequest request) throws Exception {
         return new RootNode(this) {
             @Override
             public Object execute(VirtualFrame frame) {
                 // fast read
                 ExampleLocal local = threadLocal.get();
                 // access local
                 return "";
             }
         }.getCallTarget();
     }

     static final class ExampleLocal {

         final Env env;
         final WeakReference thread;

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

     }
 }
 

Since:

23.1