Class TruffleLanguage.ContextLocalProvider<C>
- Enclosing class:
TruffleLanguage<C>
- Since:
- 23.1
- See Also:
-
Method Summary
Modifier and TypeMethodDescription<T> ContextLocal
<T> createContextLocal
(TruffleLanguage.ContextLocalFactory<C, T> factory) Creates a new context local reference for this Truffle language.<T> ContextThreadLocal
<T> Creates a new context thread local reference for this Truffle language.
-
Method Details
-
createContextLocal
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 anIllegalStateException
. For each registeredTruffleLanguage
subclass it is required to always produce the same number of context local references. The values produced by the factory must not benull
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 ornull
then anIllegalStateException
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 anIllegalStateException
. For each registeredTruffleLanguage
subclass it is required to always produce the same number of context thread local references. The values produced by the factory must not benull
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 ornull
then anIllegalStateException
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
-