com.oracle.truffle.api.vm

Class PolyglotEngine

java.lang.Object

com.oracle.truffle.api.vm.PolyglotEngine

public class PolyglotEngine
extends Object

A multi-language execution environment for Truffle-implemented languages that supports interoperability among the Truffle languages and with Java, for example cross-language calls, foreign object exchange, and shared global symbols. The environment also includes a framework for instrumentation that supports both built-in services, for example debugging and profiling, as well as API access to dynamic execution state for external tools.

For a simple example see eval(Source). The Truffle Tutorial provides much more general information about Truffle. For information specifically related to Java applications, the tutorial Embedding Truffle Languages in Java explains, with examples, how Java code can directly access guest language functions, objects, classes, and some complex data structures with Java-typed accessors. In the reverse direction, guest language code can access Java objects, classes, and constructors.

Engine Creation

The Builder creates new engine instances and allows both application- and language-specific configuration. The following example creates a default instance.

PolyglotEngine engine = PolyglotEngine.newBuilder().build();

Truffle Languages

An engine supports every Truffle language available on the host JVM class path.

Languages are initialized on demand, the first time an engine evaluates code of a matching MIME type. The engine throws an IllegalStateException if no matching language is available. Languages remain initialized for the lifetime of the engine.

Specific language environments can be configured, for example in response to command line options, by building the engine with combinations of language-specific MIME-key-value settings ( Builder.config(String, String, Object)) and pre-registered global symbols (Builder.globalSymbol(String, Object) )

Global Symbols

An engine supports communication among languages via shared named values known as global symbols. These typically implement guest language export/import statements used for language interoperation.

Each language dynamically manages a namespace of global symbols. The engine provides its own (static) namespace, configured when the engine is built ( Builder.globalSymbol(String, Object)).

An engine retrieves global symbols by name, first searching the engine's namespace, and then searching all language namespaces in unspecified order, returning the first one found ( findGlobalSymbol(String)). Name collisions across namespaces are possible and can only be discovered by explicitly retrieving all global symbols with a particular name (findGlobalSymbols(String)).

Truffle Cross-language Interoperation

Interoperability among executing guest language programs is supported in part by the cross-language exchange of global symbols whose retrieval produces results wrapped Value instances. The content of a Value may be a boxed Java primitive type or a foreign object (implemented internally as a TruffleObject). Foreign objects support a message-based protocol for access to their contents, possibly including fields and methods.

Foreign objects may be functional, in which case cross-language method/procedure calls are possible. Foreign calls return results wrapped in non-null Value instances.

Truffle-Java Interoperation

Interoperability is also supported between Java and guest language programs. For example a Java client can export global symbols during engine creation ( Builder.globalSymbol(String, Object)) and import them at any time (findGlobalSymbol(String)). The content of a Value (for example retrieved from an imported symbol) can be accessed (Value.as(Class)) as an object of requested type (a kind of cross-langauge "cast"). A Value determined to be functional can be called (Value.execute(Object...)) and will return the result wrapped in a non-null Value instance.

Java clients export values in two ways:

• bound to globally accessible names (Builder.globalSymbol(String, Object)), or
• as arguments to foreign method/procedure calls (Value.execute(Object...)).

In either case the engine wraps exported non-primitive Java values so that they appear to guest languages the same as other foreign objects. In situations where a Java object is exported and eventually returned (by import or method/procedure call), the identity of the result (obtained by Value.get()) is preserved.

Exporting a Java object grants guest language access to the object's public fields and methods. Exporting a Java class grants guest language access to the class's public static fields and public constructors.

Engine Isolation

Engines are isolated using the runtime they are assocated with. A runtime is associated with one or more polyglot engines. One runtime is a isolated tenant on a host Virtual Machine. Other than shared host resources such as memory, no aspects of program execution, language environments, or global symbols are shared with other runtimes.

Threading

Guest language code execution is single-threaded, performed on a thread determined by the engine's configuration.

• Execution (eval(Source)) is by default synchronous (performed on the calling thread) and only permitted on the thread that created the engine.
• An engine can be configured with a custom Executor (Builder.executor(Executor)) that performs executions on a different thread. In this case the engine requires only that all executions are performed on the same thread.

In contrast, instrumentation-based access to engine state is thread-safe, both from built-in services such as debugging and profiling as well as from external tools.

Since:

0.9

See Also:

More information for language implementors.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	PolyglotEngine.Builder A builder for creating an engine instance.
class	PolyglotEngine.Language A handle for a Truffle language installed in a PolyglotEngine.
class	PolyglotEngine.Value A future value wrapper.

Method Summary

Modifier and Type	Method and Description
void	dispose() Disposes this engine instance and releases all resources allocated by languages active in this engine.
PolyglotEngine.Value	eval(Source source) Evaluates guest language source code, using the installed Language that matches the code's MIME type.
PolyglotEngine.Value	findGlobalSymbol(String globalName) Finds a global symbol by name.
Iterable<PolyglotEngine.Value>	findGlobalSymbols(String globalName) Finds all global symbols with a specified name by searching every language's namespace of exported symbols, together with the the engine's namespace of preconfigured symbols.
Map<String,? extends PolyglotEngine.Language>	getLanguages() Gets the map: MIME type --> metadata for the matching language installed in this engine, whether or not the language has been initialized.
PolyglotRuntime	getRuntime() Access to associated runtime.
static PolyglotEngine.Builder	newBuilder() Returns a builder for creating an engine instance.

Methods inherited from class java.lang.Object

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

Method Detail

newBuilder

public static PolyglotEngine.Builder newBuilder()

Returns a builder for creating an engine instance. After any configuration methods have been called, the final build() step creates the engine and installs all available languages. For example:

 PolyglotEngine engine = PolyglotEngine.newBuilder()
     .setOut(yourOutput)
     .setErr(yourOutput)
     .setIn(yourInput)
     .build();
 

Returns:

a builder to create a new engine with all available languages installed

Since:

0.10

getLanguages

public Map<String,? extends PolyglotEngine.Language> getLanguages()

Gets the map: MIME type --> metadata for the matching language installed in this engine, whether or not the language has been initialized.

Returns:

an immutable map: MIME type --> metadata for the language that supports the source type

Since:

0.9

getRuntime

public PolyglotRuntime getRuntime()

Access to associated runtime.

Returns:

the runtime associated with this engine

Since:

0.25

eval

public PolyglotEngine.Value eval(Source source)

Evaluates guest language source code, using the installed Language that matches the code's MIME type. Source code is provided to the engine as Source objects, which may wrap references to guest language code (e.g. a filename or URL) or may represent code literally as in the example below. The engine returns the result wrapped in an instance of Value, for which Java-typed access (objects) can be created using Value.as(Class).

Source src = Source.newBuilder("3 + 39").
                mimeType("application/my-test-lang").
                name("example.test-lang").
                build();
PolyglotEngine engine = PolyglotEngine.newBuilder().build();
PolyglotEngine.Value result = engine.eval(src);
int answer = result.as(Integer.class);

For sources marked as interactive, the engine will will do more, depending the language. This may include printing the result, in a language-specific format, to the engine's standard output. It might read input values queried by the language.

This method is useful for Java applications that interoperate with guest languages. The general strategy is to evaluate guest language code that produces the desired language element and then create a Java object of the appropriate type for Java foreign access to the result. The tutorial "Embedding Truffle Languages in Java" contains examples.

Parameters:

source - guest language code

Returns:

result of the evaluation wrapped in a non-null PolyglotEngine.Value

Throws:

IllegalStateException - if no installed language matches the code's MIME type

Exception - thrown to signal errors while processing the code

Since:

0.9

See Also:

PolyglotEngine.Value.as(Class)

dispose

public void dispose()

Disposes this engine instance and releases all resources allocated by languages active in this engine. If a default/private runtime is configured for this engine then it is disposed automatically with this engine.

Calling any other method on this instance after disposal throws an IllegalStateException.

Since:

0.9

findGlobalSymbol

public PolyglotEngine.Value findGlobalSymbol(String globalName)

Finds a global symbol by name. Returns the symbol in the engine's namespace of preconfigured global symbols, if present. Otherwise returns the first symbol found, if any, in a language namespace, which are queried in an unspecified order.

Symbol names are language dependent. Cross-language name collisions are possible, in which case this method only returns one of them (use PolyglotEngine.findGlobalSymbols(String) to return all of them).

Parameters:

globalName - a global symbol name

Returns:

the value of a global symbol with the specified name, null if none

Since:

0.9

findGlobalSymbols

public Iterable<PolyglotEngine.Value> findGlobalSymbols(String globalName)

Finds all global symbols with a specified name by searching every language's namespace of exported symbols, together with the the engine's namespace of preconfigured symbols.

The following example shows how this method can be used to retrieve a single global symbol, while treating name collisions as an error.

static PolyglotEngine.Value findAndReportMultipleExportedSymbols(
                  PolyglotEngine engine, String name) {
    PolyglotEngine.Value found = null;
    for (PolyglotEngine.Value value : engine.findGlobalSymbols(name)) {
        if (found != null) {
            throw new IllegalStateException(
                "Multiple global symbols exported with " + name + " name"
            );
        }
        found = value;
    }
    return found;
}

Parameters:

globalName - a global symbol name

Returns:

iterable access to the values of global symbols with the specified name

Since:

0.22