public abstract static class TruffleLanguage.ContextReference<C> extends Object
TruffleLanguage.ContextReference.create(Class)
and are intended to be stored in static final fields and accessed at
runtime using TruffleLanguage.ContextReference.get(Node)
with the current Node
, if available,
as parameter.
Example intended usage:
public final class MyContext { private static final ContextReference<MyContext> REFERENCE = ContextReference.create(MyLanguage.class); public static MyContext get(Node node) { return REFERENCE.get(node); } } @Registration(...) public final class MyLanguage extends TruffleLanguage{ // ... private static final LanguageReference<MyLanguage> REFERENCE = LanguageReference.create(MyLanguage.class); public static MyLanguage get(Node node) { return REFERENCE.get(node); } } public final class MyLanguageNode extends Node { // ... public Object execute(VirtualFrame frame) { MyContext currentContext = getContext(); MyLanguage currentLanguage = getLanguage(); // use context or language on the fast-path // references can also be used behind the boundary exampleBoundary(); } @TruffleBoundary public void exampleBoundary() { MyLanguage currentLanguage = MyLanguage.get(null); MyContext currentContext = MyContext.get(null); // use context or language on the slow-path } public final MyLanguage getLanguage() { return MyLanguage.get(this); } public final MyContext getContext() { return MyContext.get(this); } }
Modifier | Constructor and Description |
---|---|
protected |
ContextReference()
Constructors for subclasses.
|
Modifier and Type | Method and Description |
---|---|
static <T extends TruffleLanguage<C>,C> |
create(Class<T> languageClass)
Creates a new instance of a context reference for an registered language.
|
abstract C |
get(Node node)
Returns the current language context associated with the current thread.
|
protected ContextReference()
public abstract C get(Node node)
null
may be
provided. This method is designed to be called safely from compiled code paths. In order
to maximize efficiency in compiled code paths, a partial evaluation constant and adopted
node should be passed as parameter. If this is the case then the return context will get
constant folded in compiled code paths if there is a only single language instance for
the enclosing engine or lookup location/node.
The current context might vary between executions
if resources or code is shared
between multiple contexts or
when used as part of an InteropLibrary export. It is recommended to *not* cache values of
the context in the AST to reduce footprint. Getting it through a context reference will
either constant fold or be very efficient in compiled code paths.
If a context is accessed during context
creation
, on an unknown Thread, or in the language class constructor an
IllegalStateException
is thrown.
for a full usage example
public static <T extends TruffleLanguage<C>,C> TruffleLanguage.ContextReference<C> create(Class<T> languageClass)
IllegalArgumentException
if the provided language class is not
registered
. Guaranteed to always return the same context reference
for a given language class.
See TruffleLanguage.ContextReference
for a usage example.