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 for executing guest language code in a PolyglotEngine. Subclasses of TruffleLanguage 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.

A new language implementation instance is instantiated for each runtime that is created using the runtime builder. If an engine is created without a runtime then the language implementation instance is created for each engine.

Global state can be shared between multiple context instances by saving them as in a field of the TruffleLanguage subclass. The implementation needs to ensure data isolation between the contexts. However ASTs or 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 language implementation instances should be used instead.

The methods in TruffleLanguage might be invoked from multiple threads. However, one context instance is guaranteed to be invoked only from one single thread. Therefore context objects don't need to be thread-safe. Code that is shared using the TruffleLanguage instance needs to be prepared to be accessed from multiple threads.

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

Cardinalities

One host virtual machine depends on other system instances using the following cardinalities:

 K = number of installed languages
 I = number of installed instruments
 N = unbounded

 - 1:Host VM Processs
   - N:PolyglotRuntime
     - K:TruffleLanguage
     - I:PolyglotRuntime.Instrument
       - 1:TruffleInstrument
   - N:PolyglotEngine
     - 1:Thread
     - K:PolyglotEngine.Language
       - 1:Language Context
 

Language Configuration

Each engine instance can, during its creation, register language-specific configuration data (for example originating from command line arguments) in the form of MIME-type/key/object triples. A Language implementation retrieves the data via TruffleLanguage.Env.getConfig() for configuring initial execution state.

Global Symbols

Language implementations communicate with one another (and with instrumentation-based tools such as debuggers) by exporting/importing named values known as global symbols. These typically implement guest language export/import statements used for language interoperation.

A language manages its namespace of exported global symbols dynamically, by its response to the query TruffleLanguage.findExportedSymbol(Object, String, boolean). No attempt is made to avoid cross-language name conflicts.

A language implementation can also import a global symbol by name, according to the following rules:

• A global symbol registered by the engine will be returned, if any, ignoring global symbols exported by other languages.
• Otherwise all languages are queried in unspecified order, and the first global symbol found, if any, is returned.

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 PolyglotEngine, 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.

Since:

0.8 or earlier

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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.ParsingRequest Request for parsing.
static interface	TruffleLanguage.Registration The annotation to use to register your language to the Truffle system.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
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 abstract Object	findExportedSymbol(C context, String globalName, boolean onlyExplicit) Called when some other language is seeking for a global symbol.
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.
TruffleLanguage.ContextReference<C>	getContextReference() Creates a reference to the current context to be stored in an AST.
protected abstract Object	getLanguageGlobal(C context) Returns global object for the language.
protected void	initializeContext(C context) Perform any complex initialization.
protected abstract boolean	isObjectOfLanguage(Object object) Checks whether the object is provided by this language.
protected boolean	isVisible(C context, Object value) Decides whether the result of evaluating an interactive source should be printed to stdout.
protected CallTarget	parse(TruffleLanguage.ParsingRequest request) Parses the provided source and generates its appropriate AST representation.
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

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 PolyglotEngine or in a new thread, 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. Should there be a need to perform complex initializaton, do it by overriding the TruffleLanguage.initializeContext(java.lang.Object) method.

Parameters:

env - the environment the language is supposed to operate in

Returns:

internal data of the language in given environment

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 initializaton, 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("function mul(x, y) { return x * y }").
            name("mul.js").
            mimeType("text/javascript").
            build();
        context.mul = context.env.parse(source);
    }
}

Parameters:

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

Throws:

Exception - if something goes wrong

Since:

0.17

disposeContext

protected void disposeContext(C context)

Disposes the context created by TruffleLanguage.createContext(com.oracle.truffle.api.TruffleLanguage.Env). A language can be asked by its user to clean-up. In such case the language is supposed to dispose any resources acquired before and dispose the context - e.g. render it useless for any future calls.

Parameters:

context - the context created by the language

Since:

0.8 or earlier

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 parsing may be performed in a context (specified by TruffleLanguage.ParsingRequest.getLocation()) or without context. 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.

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 parsing goes wrong. Here-in thrown exception is propagated to the user who called one of eval methods of PolyglotEngine

Since:

0.22

findExportedSymbol

protected abstract Object findExportedSymbol(C context,
                                             String globalName,
                                             boolean onlyExplicit)

Called when some other language is seeking for a global symbol. This method is supposed to do lazy binding, e.g. there is no need to export symbols in advance, it is fine to wait until somebody asks for it (by calling this method).

The exported object can either be TruffleObject (e.g. a native object from the other language) to support interoperability between languages, String or one of the Java primitive wrappers ( Integer, Double, Short, Boolean, etc.).

The way a symbol becomes exported is language dependent. In general it is preferred to make the export explicit - e.g. call some function or method to register an object under specific name. Some languages may however decide to support implicit export of symbols (for example from global scope, if they have one). However explicit exports should always be preferred. Implicitly exported object of some name should only be used when there is no explicit export under such globalName. To ensure so the infrastructure first asks all known languages for onlyExplicit symbols and only when none is found, it does one more round with onlyExplicit set to false.

Parameters:

context - context to locate the global symbol in

globalName - the name of the global symbol to find

onlyExplicit - should the language seek for implicitly exported object or only consider the explicitly exported ones?

Returns:

an exported object or null, if the symbol does not represent anything meaningful in this language

Since:

0.8 or earlier

getLanguageGlobal

protected abstract Object getLanguageGlobal(C context)

Returns global object for the language.

The object is expected to be TruffleObject (e.g. a native object from the other language) but technically it can be one of the Java primitive wrappers (Integer, Double, Short, etc.).

Parameters:

context - context to find the language global in

Returns:

the global object or null if the language does not support such concept

Since:

0.8 or earlier

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

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.as(String.class) 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 PolyglotEngine.eval(com.oracle.truffle.api.source.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 polyglot engine output, error and input streams. When PolyglotEngine.eval(com.oracle.truffle.api.source.Source) is called over an interactive source of a language that controls its interactive behavior, it is the reponsibility of the language itself to print the result to standard output or error output and/or access standard input in an appropriate way.

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.

When no meta-object is known, return null. The default implementation returns null.

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