com.oracle.truffle.api

Class TruffleLanguage.ContextReference<C>

java.lang.Object

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

Enclosing class:

TruffleLanguage<C>

public abstract static class TruffleLanguage.ContextReference<C>
extends Object

Represents a reference to the current context. The current context is a thread local value that changes when polyglot context is entered or left. Context references are created using 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);
     }
 }
 

Since:

0.25 revised in 21.3

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ContextReference() Constructors for subclasses.

Method Summary

Modifier and Type	Method and Description
static <T extends TruffleLanguage<C>,C> TruffleLanguage.ContextReference<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.

Methods inherited from class java.lang.Object

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

Constructor Detail

ContextReference

protected ContextReference()

Constructors for subclasses.

Since:

19.0

Method Detail

get

public abstract C get(Node node)

Returns the current language context associated with the current thread. An enclosing node should be provided as parameter if available, otherwise 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.

Since:

21.3

See Also:

for a full usage example

create

public static <T extends TruffleLanguage<C>,C> TruffleLanguage.ContextReference<C> create(Class<T> languageClass)

Creates a new instance of a context reference for an registered language. Throws 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.

Since:

21.3