Class TruffleLanguage.LanguageReference<L extends TruffleLanguage>

java.lang.Object
com.oracle.truffle.api.TruffleLanguage.LanguageReference<L>
Enclosing class:
TruffleLanguage<C>
public abstract static class TruffleLanguage.LanguageReference<L extends TruffleLanguage> extends Object
Represents a reference to the current language instance. The current language is a thread local value that potentially changes when polyglot context is entered or left. Language references are created using create(Class) and are intended to be stored in static final fields and accessed at runtime using get(Node) with the current Node, if available, as parameter.

Example intended usage: See TruffleLanguage.ContextReference for a full usage example.

Since:
0.25 revised in 21.3

  • Constructor Details

    • LanguageReference

      protected LanguageReference()
      Constructors for subclasses.
      Since:
      19.0

  • Method Details

    • get

      public abstract L get(Node node)
      Returns the current language instance 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 context instance for the enclosing engine or lookup location/node.

      The current language will not change for executions of roots of the current language. For roots of other languages, e.g. if invoked through the interoperability protocol, the language might change between consecutive executions. It is recommended to *not* cache values of the language in the AST to reduce footprint. Getting it through a language 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:

    • create

      public static <T extends TruffleLanguage<?>> TruffleLanguage.LanguageReference<T> create(Class<T> languageClass)
      Creates a new instance of a langauge 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.LanguageReference for a usage example.

      Since:
      21.3