com.oracle.truffle.api

Class TruffleLanguage<C>

java.lang.Object

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

Type Parameters:

C - internal state of the language associated with every thread that is executing program parsed by the language

public abstract class TruffleLanguage<C>
extends Object

A Truffle language implementation contains all the services a language should provide to make it composable with other languages. Implementation classes must be annotated with TruffleLanguage.Registration in order to be discoverable by the Polyglot API. TruffleLanguage subclasses must provide a public default constructor.

Lifecycle

A language implementation becomes available for use by an engine when metadata is added using the TruffleLanguage.Registration annotation and the implementation's JAR file placed on the host Java Virtual Machine's class path.

A newly created engine locates all available language implementations and creates a descriptor for each. The descriptor holds the language's registered metadata, but its execution environment is not initialized until the language is needed for code execution. That execution environment remains initialized for the lifetime of the engine and is isolated from the environment in any other engine instance.

Language global state can be shared between multiple context instances by saving them in a custom field of the TruffleLanguage subclass. Languages may control sharing between multiple contexts using its context policy. By default the context policy is exclusive: each context has its own separate TruffleLanguage instance.

If the context policy is more permissive then the implementation needs to manually ensure data isolation between the contexts. This means that state associated with a context must not be stored in a TruffleLanguage subclass. ASTs and assumptions can be shared across multiple contexts if modifying them does not affect language semantics. Languages are strongly discouraged from using static mutable state in their languages. Instead TruffleLanguage instances should be used instead to store global state and their sharing should be configured using context policy.

Whenever an engine is disposed then each initialized language context will be disposed.

Context Policy

The number of TruffleLanguage instances per polyglot context is configured by the context policy. By default an exclusive language instance is created for every polyglot context or inner context. With policy reuse, language instances will be reused after a language context was disposed. With policy shared, a language will also be reused if active contexts are not yet disposed. Language instances will only be shared or reused if they are compatible. Language implementations are encouraged to support the most permissive context policy possible. Please see the individual policies for details on the implications on the language implementation.

The following illustration shows the cardinalities of the individual components:

  N: unbounded
  P: N for exclusive, 1 for shared context policy
  L: number of installed languages
  I: number of installed instruments

  - 1 : Host VM Processs
   - N : Engine
     - N : Context
       - L : Language Context
     - P * L : TruffleLanguage
     - I : Instrument
       - 1 : TruffleInstrument
 

Parse Caching

The result of the parsing request is cached per language instance, source, argument names and environment options. The scope of the caching is influenced by the context policy. Caching may be disabled for certain sources. It is enabled for new sources by default.

Language Configuration

On context creation each language context is provided with information about the environment environment . Language can optionally declare configurable options in TruffleLanguage.getOptionDescriptors().

Polyglot Bindings

Language implementations communicate with one another (and with instrumentation-based tools such as debuggers) by reading/writing named values into the polyglot bindings. This bindings object is used to implement guest language export/import statements used for language interoperation.

A language implementation can also import or export a global symbol by name. The scope may be accessed from multiple threads at the same time. Existing keys are overwritten.

Configuration vs. Initialization

To ensure that a Truffle language can be used in a language-agnostic way, the implementation should be designed to decouple its configuration and initialization from language specifics as much as possible. One aspect of this is the initialization and start of execution via the Context, which should be designed in a generic way. Language-specific entry points, for instance to emulate the command-line interface of an existing implementation, should be handled externally.

Multi-threading

There are two kinds of threads that access contexts of Truffle guest languages:

• Internal threads are created and managed by a language for a context. All internally created threads need to be stopped when the context is disposed.
• External threads are created and managed by the host application / language launcher. The host application is allowed to use language contexts from changing threads, sequentially or at the same time if the language allows it.

By default every context only allows access from one thread at the same time. Therefore if the context is tried to be accessed from multiple threads at the same time the access will fail. Languages that want to allow multi-threaded access to a context may override TruffleLanguage.isThreadAccessAllowed(Thread, boolean) and return true also for multi-threaded accesses. Initialization actions for multi-threaded access can be performed by overriding TruffleLanguage.initializeMultiThreading(Object). Threads are initialized and disposed before and after use with a context. Languages may create new threads if the environment allows it.

Since:

0.8 or earlier

See Also:

for embedding of Truffle languages in Java host applications.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TruffleLanguage.ContextPolicy Defines the supported policy for reusing languages per context.
static class	TruffleLanguage.ContextReference<C> Represents a reference to the current context to be stored in an AST.
static class	TruffleLanguage.Env Represents execution environment of the TruffleLanguage.
static class	TruffleLanguage.InlineParsingRequest Request for inline parsing.
static class	TruffleLanguage.LanguageReference<L extends TruffleLanguage> Represents a reference to the language to be stored in an AST.
static class	TruffleLanguage.ParsingRequest Request for parsing.
static interface	TruffleLanguage.Registration The annotation to use to register your language to the Polyglot API.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TruffleLanguage() Constructor to be called by subclasses.

Method Summary

Modifier and Type	Method and Description
protected boolean	areOptionsCompatible(org.graalvm.options.OptionValues firstOptions, org.graalvm.options.OptionValues newOptions) Returns true if the combination of two sets of options allow to share or reuse the same language instance, else false.
protected abstract C	createContext(TruffleLanguage.Env env) Creates internal representation of the executing context suitable for given environment.
protected void	disposeContext(C context) Disposes the context created by TruffleLanguage.createContext(com.oracle.truffle.api.TruffleLanguage.Env).
protected void	disposeThread(C context, Thread thread) Invoked the last time code will be executed for this thread and context.
protected void	finalizeContext(C context) Performs language context finalization actions that are necessary before language contexts are disposed.
protected Iterable<Scope>	findLocalScopes(C context, Node node, Frame frame) Find a hierarchy of local scopes enclosing the given node.
protected Object	findMetaObject(C context, Object value) Find a meta-object of a value, if any.
protected SourceSection	findSourceLocation(C context, Object value) Find a source location where a value is declared, if any.
protected Iterable<Scope>	findTopScopes(C context) Find a hierarchy of top-most scopes of the language, if any.
TruffleLanguage.ContextReference<C>	getContextReference() Creates a reference to the current context to be stored in an AST.
protected static <C,T extends TruffleLanguage<C>> C	getCurrentContext(Class<T> languageClass) Returns the current language context entered on the current thread.
protected static <T extends TruffleLanguage<?>> T	getCurrentLanguage(Class<T> languageClass) Returns the current language instance for the current thread.
protected String	getLanguageHome() Returns the home location for this language.
protected org.graalvm.options.OptionDescriptors	getOptionDescriptors() Returns a set of option descriptors that are supported by this language.
protected void	initializeContext(C context) Perform any complex initialization.
protected void	initializeMultipleContexts() Initializes this language instance for use with multiple contexts.
protected void	initializeMultiThreading(C context) Invoked before the context is accessed from multiple threads at the same time.
protected void	initializeThread(C context, Thread thread) Invoked before a context is accessed from a new thread.
protected abstract boolean	isObjectOfLanguage(Object object) Checks whether the object is provided by this language.
protected boolean	isThreadAccessAllowed(Thread thread, boolean singleThreaded) Returns true if code of this language is allowed to be executed on this thread.
protected boolean	isVisible(C context, Object value) Decides whether the result of evaluating an interactive source should be printed to stdout.
protected ExecutableNode	parse(TruffleLanguage.InlineParsingRequest request) Parses the provided source snippet at the provided location and generates its appropriate AST representation.
protected CallTarget	parse(TruffleLanguage.ParsingRequest request) Parses the provided source and generates its appropriate AST representation.
protected boolean	patchContext(C context, TruffleLanguage.Env newEnv) Notifies the language with pre-initialized context about TruffleLanguage.Env change.
protected String	toString(C context, Object value) Generates language specific textual representation of a value.

Methods inherited from class java.lang.Object

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

Constructor Detail

TruffleLanguage

protected TruffleLanguage()

Constructor to be called by subclasses.

Since:

0.8 or earlier

Method Detail

areOptionsCompatible

protected boolean areOptionsCompatible(org.graalvm.options.OptionValues firstOptions,
                                       org.graalvm.options.OptionValues newOptions)

Returns true if the combination of two sets of options allow to share or reuse the same language instance, else false. If options are incompatible then a new language instance will be created for a new context. The first language context created for a TruffleLanguage instance always has compatible options, therefore TruffleLanguage.areOptionsCompatible(OptionValues, OptionValues) will not be invoked for it. The default implementation returns true.

If the context policy of a language is set to exclusive (default behavior) then TruffleLanguage.areOptionsCompatible(OptionValues, OptionValues) will never be invoked as TruffleLanguage instances will not be shared for multiple contexts. For the other context policies reuse and shared this method can be used to further restrict the reuse of language instances. Compatibility influences parse caching because it uses the language instance as a key.

Example usage of areOptionsCompatible if sharing of the language instances and parse caching should be restricted by the script version option:

class CompatibleLanguage extends TruffleLanguage<TruffleLanguage.Env> {

    @Option(help = "", category = OptionCategory.USER)
    static final OptionKey<String> ScriptVersion
                = new OptionKey<>("ECMA2017");

    @Override
    protected boolean areOptionsCompatible(OptionValues firstOptions,
                    OptionValues newOptions) {
        return firstOptions.get(ScriptVersion).
                        equals(newOptions.get(ScriptVersion));
    }

    @Override
    protected OptionDescriptors getOptionDescriptors() {
        return new CompatibleLanguageOptionDescriptors();
    }
}

Parameters:

firstOptions - the options used to create the first context, never null

newOptions - the options that will be used for the new context, never null

Since:

19.0

See Also:

TruffleLanguage.ContextPolicy, TruffleLanguage.parse(ParsingRequest)

createContext

protected abstract C createContext(TruffleLanguage.Env env)

Creates internal representation of the executing context suitable for given environment. Each time the language is used by a new Context, the system calls this method to let the language prepare for execution. The returned execution context is completely language specific; it is however expected it will contain reference to here-in provided env and adjust itself according to parameters provided by the env object.

The context created by this method is accessible using TruffleLanguage.getContextReference(). An IllegalStateException is thrown if the context is tried to be accessed while the createContext method is executed.

This method shouldn't perform any complex operations. The runtime system is just being initialized and for example making calls into other languages and assuming your language is already initialized and others can see it would be wrong - until you return from this method, the initialization isn't over. The same is true for instrumentation, the instruments cannot receive any meta data about code executed during context creation. Should there be a need to perform complex initialization, do it by overriding the TruffleLanguage.initializeContext(java.lang.Object) method.

Additional services provided by the language must be registered by this method otherwise IllegalStateException is thrown.

May return null if the language does not need any per-context state. Otherwise it should return a new object instance every time it is called.

Parameters:

env - the environment the language is supposed to operate in

Returns:

internal data of the language in given environment or null

Since:

0.8 or earlier

initializeContext

protected void initializeContext(C context)
                          throws Exception

Perform any complex initialization. The TruffleLanguage.createContext(com.oracle.truffle.api.TruffleLanguage.Env) factory method shouldn't do any complex operations. Just create the instance of the context, let the runtime system register it properly. Should there be a need to perform complex initialization, override this method and let the runtime call it later to finish any post initialization actions. Example:

class PostInitLanguage extends TruffleLanguage<Context> {
    @Override
    protected Context createContext(TruffleLanguage.Env env) {
        // "quickly" create the context
        return new Context(env);
    }

    @Override
    protected void initializeContext(Context context) throws IOException {
        // called "later" to finish the initialization
        // for example call into another language
        Source source = Source.newBuilder("js",
                            "function(x, y) x * y",
                            "mul.js").build();
        context.mul = context.env.parsePublic(source);
    }
}

Parameters:

context - the context created by TruffleLanguage.createContext(com.oracle.truffle.api.TruffleLanguage.Env)

Throws:

Exception - if something goes wrong

Since:

0.17

finalizeContext

protected void finalizeContext(C context)

Performs language context finalization actions that are necessary before language contexts are disposed. All installed languages must remain usable after finalization. The finalization order can be influenced by specifying language dependencies. By default internal languages are finalized last, otherwise the default order is unspecified but deterministic.

While finalization code is run, other language contexts may become initialized. In such a case, the finalization order may be non-deterministic and/or not respect the order specified by language dependencies.

Parameters:

context - the context created by TruffleLanguage.createContext(com.oracle.truffle.api.TruffleLanguage.Env)

Since:

0.30

See Also:

for specifying language dependencies.

initializeMultipleContexts

protected void initializeMultipleContexts()

Initializes this language instance for use with multiple contexts. Whether a language instance supports being used for multiple contexts depends on its context policy.

With the default context policy exclusive, this method will never be invoked. This method will be called prior or after the first context was created for this language. In case an explicit engine was used to create a context, then this method will be invoked prior to the creation of the first language context of a language. For inner contexts, this method may be invoked prior to the first inner context that is created, but after the the first outer context was created. No guest language code must be invoked in this method. This method is called at most once per language instance.

A language may use this method to invalidate assumptions that assume a single context only. For example, assumptions that are dependent on the language context data. It is required to invalidate any such assumptions that are used in the AST when this method is invoked.

Since:

19.0

See Also:

TruffleLanguage.areOptionsCompatible(OptionValues, OptionValues), TruffleLanguage.ContextPolicy

disposeContext

protected void disposeContext(C context)

Disposes the context created by TruffleLanguage.createContext(com.oracle.truffle.api.TruffleLanguage.Env). A dispose cleans up all resources associated with a context. The context may become unusable after it was disposed. It is not allowed to run guest language code while disposing a context. Finalization code should be run in TruffleLanguage.finalizeContext(Object) instead. Finalization will be performed prior to context disposal.

The disposal order can be influenced by specifying language dependencies. By default internal languages are disposed last, otherwise the default order is unspecified but deterministic. During disposal no other language must be accessed using the language environment.

All threads created by a language must be stopped after dispose was called. The languages are responsible for fulfilling that contract otherwise an AssertionError is thrown. It is recommended to join all threads that were disposed.

Parameters:

context - the context created by TruffleLanguage.createContext(com.oracle.truffle.api.TruffleLanguage.Env)

Since:

0.8 or earlier

See Also:

to run finalization code for a context., to perform disposal actions when a thread is no longer used.

parse

protected CallTarget parse(TruffleLanguage.ParsingRequest request)
                    throws Exception

Parses the provided source and generates its appropriate AST representation. The parsing should execute no user code, it should only create the Node tree to represent the source. If the provided source does not correspond naturally to a call target, the returned call target should create and if necessary initialize the corresponding language entity and return it.

The result of the parsing request is cached per language instance, source and argument names. It is safe to assume that current language instance and argument names will remain unchanged for a parsed CallTarget. The scope of the caching is influenced by the context policy and option compatibility. Caching may be disabled for sources. It is enabled for new sources by default.

The argumentNames may contain symbolic names for actual parameters of the call to the returned value. The result should be a call target with method CallTarget.call(java.lang.Object...) that accepts as many arguments as were provided via the TruffleLanguage.ParsingRequest.getArgumentNames() method.

Implement TruffleLanguage.parse(com.oracle.truffle.api.TruffleLanguage.InlineParsingRequest) to parse source in a specific context location.

Parameters:

request - request for parsing

Returns:

a call target to invoke which also keeps in memory the Node tree representing just parsed code

Throws:

Exception - exception can be thrown when parsing goes wrong. Here-in thrown exception is propagated to the user who called one of eval methods of Context

Since:

0.22

See Also:

TruffleLanguage.Registration.contextPolicy()

parse

protected ExecutableNode parse(TruffleLanguage.InlineParsingRequest request)
                        throws Exception

Parses the provided source snippet at the provided location and generates its appropriate AST representation. The parsing should execute no user code, it should only create the Node tree to represent the source.

The parsing should be performed in a context (specified by TruffleLanguage.InlineParsingRequest.getLocation()). The result should be an AST fragment with method ExecutableNode.execute(com.oracle.truffle.api.frame.VirtualFrame) that accepts frames valid at the provided location.

When not implemented, null is returned by default.

Parameters:

request - request for parsing

Returns:

a fragment to invoke which also keeps in memory the Node tree representing just parsed code, or null when inline parsing of code snippets is not implemented

Throws:

Exception - exception can be thrown when parsing goes wrong.

Since:

0.31

getOptionDescriptors

protected org.graalvm.options.OptionDescriptors getOptionDescriptors()

Returns a set of option descriptors that are supported by this language. Option values are accessible using the environment when the context is created. To construct option descriptors from a list then OptionDescriptors.create(List) can be used. Languages must always return the same option descriptors independent of the language instance or side-effects.

Since:

0.27

See Also:

For an example of declaring the option descriptor using an annotation.

patchContext

protected boolean patchContext(C context,
                               TruffleLanguage.Env newEnv)

Notifies the language with pre-initialized context about TruffleLanguage.Env change. See Context for information how to enable the Context pre-initialization.

During the pre-initialization (in the native compilation time) the TruffleLanguage.createContext(com.oracle.truffle.api.TruffleLanguage.Env) and TruffleLanguage.initializeContext(java.lang.Object) methods are called. In the image execution time, the TruffleLanguage.patchContext(java.lang.Object, com.oracle.truffle.api.TruffleLanguage.Env) is called on all pre-initialized languages as a consequence of Context.create(java.lang.String...) invocation. The contexts are patched in a topological order starting from dependent languages. If the TruffleLanguage.patchContext(java.lang.Object, com.oracle.truffle.api.TruffleLanguage.Env) is successful for all pre-initialized languages the pre-initialized context is used, otherwise a new context is created.

Typical implementation looks like:

@Override
protected boolean patchContext(Context context, TruffleLanguage.Env newEnv) {
    if (!optionsAllowPreInitializedContext(context, newEnv)) {
        // Incompatible options - cannot use pre-initialized context
        return false;
    }
    context.env = newEnv;
    context.args = newEnv.getApplicationArguments();
    context.in = newEnv.in();
    context.out = newEnv.out();
    context.err = newEnv.err();
    return true;
}

private boolean optionsAllowPreInitializedContext(Context context, TruffleLanguage.Env newEnv) {
    // Verify that values of important options in the new Env do not differ
    // from values in the pre-initialized context
    final String newVersionValue = newEnv.getOptions().get(version);
    return Objects.equals(context.languageVersion, newVersionValue);
}

Parameters:

context - the context created by TruffleLanguage.createContext(com.oracle.truffle.api.TruffleLanguage.Env) during pre-initialization

newEnv - the new environment replacing the environment used in pre-initialization phase

Returns:

true in case of successful environment update. When the context cannot be updated to a new environment return false to create a new context. By default it returns false to prevent an usage of pre-initialized context by a language which is not aware of context pre-initialization.

Since:

0.31

isThreadAccessAllowed

protected boolean isThreadAccessAllowed(Thread thread,
                                        boolean singleThreaded)

Returns true if code of this language is allowed to be executed on this thread. The method returns false to deny execution on this thread. The default implementation denies access to more than one thread at the same time. The current thread may differ from the passed thread.

Example multi-threaded language implementation:

class MultiThreadedLanguage extends TruffleLanguage<Context> {

    @Override
    protected Context createContext(TruffleLanguage.Env env) {
        return new Context(env);
    }

    @Override
    protected boolean isThreadAccessAllowed(Thread thread,
                    boolean singleThreaded) {
        // allow access from any thread instead of just one
        return true;
    }

    @Override
    protected void initializeMultiThreading(Context context) {
        // perform actions when the context is switched to multi-threading
        context.singleThreaded.invalidate();
    }

    @Override
    protected void initializeThread(Context context, Thread thread) {
        // perform initialization actions for threads
    }

    @Override
    protected void disposeThread(Context context, Thread thread) {
        // perform disposal actions for threads
    }
}

Parameters:

thread - the thread that accesses the context for the first time.

singleThreaded - true if the access is considered single-threaded, false if more than one thread is active at the same time.

Since:

0.28

initializeMultiThreading

protected void initializeMultiThreading(C context)

Invoked before the context is accessed from multiple threads at the same time. This allows languages to perform actions that are required to support multi-threading. It will never be invoked if TruffleLanguage.isThreadAccessAllowed(Thread, boolean) is implemented to deny access from multiple threads at the same time. All initialized languages must allow multi-threading for this method to be invoked.

Example multi-threaded language implementation:

class MultiThreadedLanguage extends TruffleLanguage<Context> {

    @Override
    protected Context createContext(TruffleLanguage.Env env) {
        return new Context(env);
    }

    @Override
    protected boolean isThreadAccessAllowed(Thread thread,
                    boolean singleThreaded) {
        // allow access from any thread instead of just one
        return true;
    }

    @Override
    protected void initializeMultiThreading(Context context) {
        // perform actions when the context is switched to multi-threading
        context.singleThreaded.invalidate();
    }

    @Override
    protected void initializeThread(Context context, Thread thread) {
        // perform initialization actions for threads
    }

    @Override
    protected void disposeThread(Context context, Thread thread) {
        // perform disposal actions for threads
    }
}

Parameters:

context - the context that should be prepared for multi-threading.

Since:

0.28

initializeThread

protected void initializeThread(C context,
                                Thread thread)

Invoked before a context is accessed from a new thread. This allows the language to perform initialization actions for each thread before guest language code is executed. Also for languages that deny access from multiple threads at the same time, multiple threads may be initialized if they are used sequentially. This method will be invoked before the context is initialized for the thread the context will be initialized with.

The current thread may differ from the initialized thread.

Example multi-threaded language implementation:

class MultiThreadedLanguage extends TruffleLanguage<Context> {

    @Override
    protected Context createContext(TruffleLanguage.Env env) {
        return new Context(env);
    }

    @Override
    protected boolean isThreadAccessAllowed(Thread thread,
                    boolean singleThreaded) {
        // allow access from any thread instead of just one
        return true;
    }

    @Override
    protected void initializeMultiThreading(Context context) {
        // perform actions when the context is switched to multi-threading
        context.singleThreaded.invalidate();
    }

    @Override
    protected void initializeThread(Context context, Thread thread) {
        // perform initialization actions for threads
    }

    @Override
    protected void disposeThread(Context context, Thread thread) {
        // perform disposal actions for threads
    }
}

Parameters:

context - the context that is entered

thread - the thread that accesses the context for the first time.

Since:

0.28

disposeThread

protected void disposeThread(C context,
                             Thread thread)

Invoked the last time code will be executed for this thread and context. This allows the language to perform cleanup actions for each thread and context. Threads might be disposed before after or while a context is disposed. The current thread may differ from the disposed thread.

Example multi-threaded language implementation:

class MultiThreadedLanguage extends TruffleLanguage<Context> {

    @Override
    protected Context createContext(TruffleLanguage.Env env) {
        return new Context(env);
    }

    @Override
    protected boolean isThreadAccessAllowed(Thread thread,
                    boolean singleThreaded) {
        // allow access from any thread instead of just one
        return true;
    }

    @Override
    protected void initializeMultiThreading(Context context) {
        // perform actions when the context is switched to multi-threading
        context.singleThreaded.invalidate();
    }

    @Override
    protected void initializeThread(Context context, Thread thread) {
        // perform initialization actions for threads
    }

    @Override
    protected void disposeThread(Context context, Thread thread) {
        // perform disposal actions for threads
    }
}

Since:

0.28

isObjectOfLanguage

protected abstract boolean isObjectOfLanguage(Object object)

Checks whether the object is provided by this language.

Parameters:

object - the object to check

Returns:

true if this language can deal with such object in native way

Since:

0.8 or earlier

findLocalScopes

protected Iterable<Scope> findLocalScopes(C context,
                                          Node node,
                                          Frame frame)

Find a hierarchy of local scopes enclosing the given node. Unless the node is in a global scope, it is expected that there is at least one scope provided, that corresponds to the enclosing function. The language might provide additional block scopes, closure scopes, etc. Global top scopes are provided by TruffleLanguage.findTopScopes(java.lang.Object). The scope hierarchy should correspond with the scope nesting, from the inner-most to the outer-most. The scopes are expected to contain variables valid at the given node.

Scopes may depend on the information provided by the frame.
Lexical scopes are returned when frame argument is null.

When not overridden, the enclosing RootNode's scope with variables read from its FrameDescriptor's FrameSlots is provided by default.

The TruffleInstrument.Env.findLocalScopes(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.frame.Frame) provides result of this method to instruments.

Parameters:

context - the current context of the language

node - a node to find the enclosing scopes for. The node, is inside a RootNode associated with this language.

frame - The current frame the node is in, or null for lexical access when the program is not running, or is not suspended at the node's location.

Returns:

an iterable with scopes in their nesting order from the inner-most to the outer-most.

Since:

0.30

findTopScopes

protected Iterable<Scope> findTopScopes(C context)

Find a hierarchy of top-most scopes of the language, if any. The scopes should be returned from the inner-most to the outer-most scope order. The language may return an empty iterable to indicate no scopes. The returned scope objects may be cached by the caller per language context. Therefore the method should always return equivalent top-scopes and variables objects for a given language context. Changes to the top scope by executing guest language code should be reflected by cached scope instances. It is recommended to store the top-scopes iterable directly in the language context for efficient access.

Interpretation

In most languages, just evaluating an expression like Math is equivalent of a lookup with the identifier 'Math' in the top-most scopes of the language. Looking up the identifier 'Math' should have equivalent semantics as reading with the key 'Math' from the variables object of one of the top-most scopes of the language. In addition languages may optionally allow modification and insertion with the variables object of the returned top-scopes.

Languages may want to specify multiple top-scopes. It is recommended to stay as close as possible to the set of top-scopes that as is described in the guest language specification, if available. For example, in JavaScript, there is a 'global environment' and a 'global object' scope. While the global environment scope contains class declarations and is not insertable, the global object scope is used to insert new global variable values and is therefore insertable.

Use Cases

• Top scopes are accessible to instruments with TruffleInstrument.Env.findTopScopes(java.lang.String) . They are used by debuggers to access the top-most scopes of the language.
• Top scopes available in the polyglot API as context bindings object. When members of the bindings object are read then the first scope where the key exists is read. If a member is modified in the bindings object, then the value will be written to the first scope where the key exists. If a new member is added to the bindings object then it is added to the first variables object where the key is insertable. If a member is removed, it is only tried to be removed from the first scope of where such a key exists. If member keys are requested from the bindings object, then the variable object keys are returned sorted from first to last.

When not overridden then a single read-only scope named 'global' without any keys will be returned.

Parameters:

context - the current context of the language

Returns:

an iterable with scopes in their nesting order from the inner-most to the outer-most.

Since:

0.30

toString

protected String toString(C context,
                          Object value)

Generates language specific textual representation of a value. Each language may have special formating conventions - even primitive values may not follow the traditional Java formating rules. As such when Value.toString() is requested, it consults the language that produced the value by calling this method. By default this method calls Objects.toString(java.lang.Object).

Parameters:

context - the execution context for doing the conversion

value - the value to convert. Either primitive type or TruffleObject

Returns:

textual representation of the value in this language

Since:

0.8 or earlier

isVisible

protected boolean isVisible(C context,
                            Object value)

Decides whether the result of evaluating an interactive source should be printed to stdout. By default this methods returns true claiming all values are visible.

This method affects behavior of Context.eval(org.graalvm.polyglot.Source) - when evaluating an interactive source the result of the evaluation is tested for visibility and if the value is found visible, it gets converted to string and printed to standard output.

A language can control whether a value is or isn't printed by overriding this method and returning false for some or all values. In such case it is up to the language itself to use the TruffleLanguage.Env.out(), TruffleLanguage.Env.err() and TruffleLanguage.Env.in() streams of the environment. When evaluation is called with an interactive source of a language that controls its interactive behavior, it is the responsibility of the language itself to print the result to use the TruffleLanguage.Env.out(), TruffleLanguage.Env.err() and TruffleLanguage.Env.in() streams of the environment.

Parameters:

context - the execution context for doing the conversion

value - the value to check. Either primitive type or TruffleObject

Returns:

true if the language implements an interactive response to evaluation of interactive sources.

Since:

0.22

findMetaObject

protected Object findMetaObject(C context,
                                Object value)

Find a meta-object of a value, if any. The meta-object represents a description of the object, reveals it's kind and it's features. Some information that a meta-object might define includes the base object's type, interface, class, methods, attributes, etc.

A programmatic textual representation should be provided for meta-objects, when possible. The meta-object may have properties describing their structure.

NOTE: Allocating the meta object must not be treated as or cause any reported guest language value allocations

When no meta-object is known, return null. The default implementation returns null. The meta-object should be an interop value. An interop value can be either a TruffleObject (e.g. a native object from the other language) to support interoperability between languages or a String.

It can be beneficial for performance to return the same value for each guest type (i.e. cache the meta-objects per context).

Parameters:

context - the execution context

value - a value to find the meta-object of

Returns:

the meta-object, or null

Since:

0.22

findSourceLocation

protected SourceSection findSourceLocation(C context,
                                           Object value)

Find a source location where a value is declared, if any. This is often useful especially for retrieval of source locations of meta-objects. The default implementation returns null.

Parameters:

context - the execution context

value - a value to get the source location for

Returns:

a source location of the object, or null

Since:

0.22

getContextReference

public final TruffleLanguage.ContextReference<C> getContextReference()

Creates a reference to the current context to be stored in an AST. The current context can be accessed using the TruffleLanguage.ContextReference.get() method of the returned reference. If a context reference is created in the language class constructor an IllegalStateException is thrown. The exception is also thrown if the reference is tried to be created or accessed outside of the execution of an engine.

The returned reference identity is undefined. It might either return always the same instance or a new reference for each invocation of the method. Please note that the current context might vary between executions if resources or code is shared between multiple contexts.

Since:

0.25

getCurrentLanguage

protected static <T extends TruffleLanguage<?>> T getCurrentLanguage(Class<T> languageClass)

Returns the current language instance for the current thread. If a node is accessible then Node.lookupLanguageReference(Class) should be used instead. Throws an IllegalStateException if the language is not yet initialized or not executing on this thread. If invoked on the fast-path then languageClass must be a compilation final value.

Type Parameters:

T - the language type

Parameters:

languageClass - the exact language class needs to be provided for the lookup.

Since:

0.27

See Also:

Node.lookupLanguageReference(Class), CachedLanguage

getCurrentContext

protected static <C,T extends TruffleLanguage<C>> C getCurrentContext(Class<T> languageClass)

Returns the current language context entered on the current thread. If a node is accessible then Node.lookupContextReference(Class) should be used instead. An IllegalStateException is thrown if the language is not yet initialized or not executing on this thread. If invoked on the fast-path then languageClass must be a compilation final value.

Type Parameters:

C - the context type

T - the language type

Parameters:

languageClass - the exact language class needs to be provided for the lookup.

Since:

0.27

See Also:

Node.lookupContextReference(Class), CachedContext

getLanguageHome

protected final String getLanguageHome()

Returns the home location for this language. This corresponds to the directory in which the Jar file is located, if run from a Jar file. For an AOT compiled binary, this corresponds to the location of the language files in the default GraalVM distribution layout. executable or shared library.

Since:

19.0