com.oracle.truffle.api

Enum TruffleLanguage.ContextPolicy

java.lang.Object

java.lang.Enum<TruffleLanguage.ContextPolicy>

com.oracle.truffle.api.TruffleLanguage.ContextPolicy

All Implemented Interfaces:

Serializable, Comparable<TruffleLanguage.ContextPolicy>

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.

The context policy applies to contexts that were created using the polyglot API as well as for inner contexts. The context policy does not apply to nodes that were created using the Truffle interop protocol. Therefore, interop message nodes always need to be prepared to be used with policy TruffleLanguage.ContextPolicy.SHARED.

Since:

19.0

See Also:

To configure context policy for a language., TruffleLanguage.parse(ParsingRequest)

Enum Constant Summary

Enum Constants

Enum Constant and Description
EXCLUSIVE Use one exclusive TruffleLanguage instance per language context instance.
REUSE Use a single TruffleLanguage instance per context instance, but allow the reuse of a language instance when a context was disposed.
SHARED Use one TruffleLanguage instance for many language context instances.

Method Summary

Modifier and Type	Method and Description
static TruffleLanguage.ContextPolicy	valueOf(String name) Returns the enum constant of this type with the specified name.
static TruffleLanguage.ContextPolicy[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

EXCLUSIVE

public static final TruffleLanguage.ContextPolicy EXCLUSIVE

Use one exclusive TruffleLanguage instance per language context instance.

Using this policy has the following implications:

• Parse caching is scoped per language instance. This means the language context instance may be directly stored in instance fields of AST nodes without the use of TruffleLanguage.ContextReference. The use of TruffleLanguage.ContextReference is still recommended to simplify migration to more permissive policies.
• If the language does not allow multi-threading (default behavior) then the language instance is guaranteed to be used from one thread at a time only. Cached ASTs will not be used from multiple threads at the same time.
• TruffleLanguage.initializeMultipleContexts() is guaranteed to never be invoked.

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 Detail

values

public static TruffleLanguage.ContextPolicy[] values()

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static TruffleLanguage.ContextPolicy valueOf(String name)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null