com.oracle.truffle.api.vm

Class PolyglotEngine.Builder

java.lang.Object

com.oracle.truffle.api.vm.PolyglotEngine.Builder

Enclosing class:

PolyglotEngine

public class PolyglotEngine.Builder
extends Object

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();
 

Since:

0.9

Method Summary

Modifier and Type	Method and Description
PolyglotEngine	build() Creates an engine configured by builder methods.
PolyglotEngine.Builder	config(String mimeType, String key, Object value) Adds Language-specific initialization data to the engine being built.
PolyglotEngine.Builder	executor(Executor executor) Provides an Executor for running guest language code asynchronously, on a thread other than the calling thread.
PolyglotEngine.Builder	globalSymbol(String name, Object obj) Adds a global symbol (named value) to be exported by the engine being built.
PolyglotEngine.Builder	runtime(PolyglotRuntime polyglotRuntime) Associates the to be created engine with an execution runtime.
PolyglotEngine.Builder	setErr(OutputStream os) Configures error output for languages running in the engine being built, defaults to System.err.
PolyglotEngine.Builder	setIn(InputStream is) Configures default input for languages running in the engine being built, defaults to System.in.
PolyglotEngine.Builder	setOut(OutputStream os) Configures default output for languages running in the engine being built, defaults to System.out.

Methods inherited from class java.lang.Object

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

Method Detail

setOut

public PolyglotEngine.Builder setOut(OutputStream os)

Configures default output for languages running in the engine being built, defaults to System.out.

Parameters:

os - the stream to use as output

Returns:

this builder

Since:

0.9

setErr

public PolyglotEngine.Builder setErr(OutputStream os)

Configures error output for languages running in the engine being built, defaults to System.err.

Parameters:

os - the stream to use as output

Returns:

this builder

Since:

0.9

setIn

public PolyglotEngine.Builder setIn(InputStream is)

Configures default input for languages running in the engine being built, defaults to System.in.

Parameters:

is - the stream to use as input

Returns:

this builder

Since:

0.9

config

public PolyglotEngine.Builder config(String mimeType,
                                     String key,
                                     Object value)

Adds Language-specific initialization data to the engine being built. For example:

String[] args = {"--kernel", "Kernel.som", "--instrument", "dyn-metrics"};
PolyglotEngine.PolyglotEngine.Builder builder = PolyglotEngine.newBuilder();
builder.config(YourLang.MIME_TYPE, "CMD_ARGS", args);
PolyglotEngine engine = builder.build();

If the same key is specified multiple times for the same language, only the last one specified applies.

Parameters:

mimeType - identification of the language to which the configuration data is provided; any of the language's declared MIME types may be used

key - to identify a language-specific configuration element

value - to parameterize initial state of a language

Returns:

this builder

Since:

0.11

globalSymbol

public PolyglotEngine.Builder globalSymbol(String name,
                                           Object obj)

Adds a global symbol (named value) to be exported by the engine being built. Any guest Language can import this symbol, which takes precedence over any symbols exported under the same name by languages. Any number of symbols may be added; in case of name-collision only the last one added will be exported. The namespace of exported global symbols is immutable once the engine is built.

See "Truffle-Java Interoperation" for the implications of exporting Java data to guest languages. The following example demonstrates the export of both a Java class and a Java object:

public static final class Multiplier {
    public static int mul(int x, int y) {
        return x * y;
    }
}

public interface Multiply {
    int mul(int x, int y);
}

public static PolyglotEngine configureJavaInterop(Multiply multiply) {
    TruffleObject staticAccess = JavaInterop.asTruffleObject(Multiplier.class);
    TruffleObject instanceAccess = JavaInterop.asTruffleObject(multiply);

    PolyglotEngine engine = PolyglotEngine.newBuilder().
        globalSymbol("mul", staticAccess).
        globalSymbol("compose", instanceAccess).
        build();

    return engine;
}

The mul and compose objects are then available to any guest language.

Parameters:

name - name of the global symbol to register

obj - value of the symbol to export

Returns:

this builder

Throws:

IllegalArgumentException - if the object isn't of primitive type and cannot be converted to TruffleObject

Since:

0.9

See Also:

PolyglotEngine.findGlobalSymbol(String)

executor

public PolyglotEngine.Builder executor(Executor executor)

Provides an Executor for running guest language code asynchronously, on a thread other than the calling thread.

By default engines execute both PolyglotEngine.eval(Source) and PolyglotEngine.Value.execute(java.lang.Object...) synchronously in the calling thread.

A custom Executor is expected to perform every execution it is given (via Executor.execute(Runnable)) in order of arrival. An arbitrary thread may be used, but the engine requires that there be only one.

Parameters:

executor - the executor of code to be used by engine being built

Returns:

this builder

Since:

0.9

runtime

public PolyglotEngine.Builder runtime(PolyglotRuntime polyglotRuntime)

Associates the to be created engine with an execution runtime. By default each engine gets its own private runtime. If the same runtime is used to create multiple engines then resources and code might be cached between these engines. A private/default or disposed runtime cannot be used to construct an engine. If attempted an IllegalArgumentException is thrown. Sample usage:

PolyglotRuntime runtime = PolyglotRuntime.newBuilder().
                setOut(out).setErr(err).build();

PolyglotEngine.Builder builder = PolyglotEngine.newBuilder().
                runtime(runtime);
PolyglotEngine engine1 = builder.build();
PolyglotEngine engine2 = builder.build();
PolyglotEngine engine3 = builder.build();

Parameters:

polyglotRuntime - an instance of runtime to associate this engine with

Returns:

this builder

Since:

0.25

See Also:

PolyglotRuntime

build

public PolyglotEngine build()

Creates an engine configured by builder methods.

Returns:

a new engine with all available languages installed

Since:

0.9