Package com.oracle.truffle.api

Enum Class TruffleLanguage.ContextPolicy

java.lang.Object
java.lang.Enum<TruffleLanguage.ContextPolicy>
com.oracle.truffle.api.TruffleLanguage.ContextPolicy
All Implemented Interfaces:
Serializable, Comparable<TruffleLanguage.ContextPolicy>, Constable
Enclosing class:
TruffleLanguage<C>
public static enum TruffleLanguage.ContextPolicy extends Enum<TruffleLanguage.ContextPolicy>
Defines the supported policy for reusing languages per context. I.e. the policy specifies the degree of sharing that is allowed between multiple language contexts. The default policy is exclusive. Every language is encouraged to try to support a context policy that is as permissive as possible, where exclusive is the least and shared is the most permissive policy. Parse caching is scoped per language instance, therefore the context policy influences its behavior.

If multiple sharable languages are used at the same time, nodes of sharable languages may adopt nodes of a non-sharable languages indirectly, e.g. through Truffle interoperability. This would complicate language implementations as they would always need to support sharing for their nodes. To avoid this problem, Truffle uses sharing layers. Sharing layers ensure that every node created by a language instance can only be observed by a single language instance at a time. Sharing layers operate on the principle that all languages share the code with the same language instance or no language shares. As a convenient consequence any call to TruffleLanguage.LanguageReference.get(Node) with an adopted Node can fold to a constant during partial evaluation.

For any sharing to take place a context must be created with sharing enabled. By default sharing is disabled for polyglot contexts. Sharing can be enabled by specifying an explicit engine or using an option. Before any language is used for sharing TruffleLanguage.initializeMultipleContexts() is invoked. It is guaranteed that sharing between multiple contexts is initialized before any language context is created.

Since:
19.0
See Also:

  • Enum Constant Details

    • EXCLUSIVE

      public static final TruffleLanguage.ContextPolicy EXCLUSIVE
      Use one exclusive TruffleLanguage instance per language context instance.

      Using this policy has the following implications:

      Since:
      19.0

    • REUSE

      public static final TruffleLanguage.ContextPolicy REUSE
      Use a single TruffleLanguage instance per context instance, but allow the reuse of a language instance when a context was disposed. This policy is useful when parsed ASTs should be shared, but multiple thread execution of the AST is not yet supported by the language.

      Using this policy has the following implications:

      • Parse caching is scoped per language instance. This means language context instances must NOT be directly stored in instance fields of AST nodes and the TruffleLanguage.ContextReference must be used instead.
      • If the language does not allow access from multiple threads (default behavior) then the language instance is guaranteed to be used from one thread at a time only. In this case also cached ASTs will not be used from multiple threads at the same time. If the language allows access from multiple threads then also ASTs may be used from multiple threads at the same time.
      • TruffleLanguage.initializeMultipleContexts() will be invoked to notify the language that multiple contexts will be used with one language instance.
      • Language instance fields must only be used for data that can be shared across multiple contexts.
      Since:
      19.0

    • SHARED

      public static final TruffleLanguage.ContextPolicy SHARED
      Use one TruffleLanguage instance for many language context instances.

      Using this policy has the following implications:

      • Parse caching is scoped per language instance. With multiple language instances per context, context instances must not be directly stored in instance fields of AST nodes and the TruffleLanguage.ContextReference must be used instead.
      • All methods of the language instance and parsed ASTs may be called from multiple threads at the same time independent of whether multiple thread access is allowed for the language.
      • TruffleLanguage.initializeMultipleContexts() will be invoked to notify the language that multiple contexts will be used with one language instance.
      • Language instance fields must only be used for data that can be shared across multiple contexts and mutable data held by the language instance must be synchronized to support concurrent access.
      Since:
      19.0

  • Method Details

    • values

      public static TruffleLanguage.ContextPolicy[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static TruffleLanguage.ContextPolicy valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null