Class TruffleInstrument.ContextLocalProvider
- Enclosing class:
TruffleInstrument
- Since:
- 23.1
- See Also:
-
Method Summary
Modifier and TypeMethodDescription<T> ContextLocal
<T> Creates a new context local reference for this instrument.<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 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 iscreated
.Context local references must be created during the invocation in the
TruffleInstrument
constructor. Calling this method at a later point in time will throw anIllegalStateException
. For each registeredTruffleInstrument
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 instrument 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:
@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 iscreated
.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 produces 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:
@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
-