This documentation is for the unreleased GraalVM version.Download Early Access Builds from GitHub.

Polyglot Programming

Running Polyglot Applications
Polyglot Options
Passing Options for Language Launchers
Passing Options Programmatically
Passing Options Using JVM Arguments

GraalVM allows users to write polyglot applications that seamlessly pass values from one language to another by means of the Truffle language implementation framework (henceforth “Truffle”).

Truffle is a Java library for building programming languages implementations as interpreters for self-modifying Abstract Syntax Trees. When writing a language interpreter with Truffle, it will automatically use the Graal compiler as a just-in-time compiler for the language. By having access to this framework, a Ruby application, for example, can run on the same JVM as a Java application. Also, a host JVM-based language and a guest language can directly interoperate with each other and pass data back and forth in the same memory space.

In order to provide foreign polyglot values in the languages implemented with Truffle, the so-called polyglot interoperability protocol has been developed. This interoperability protocol consists of a set of standardized messages that every language implements and uses for foreign polyglot values. The protocol allows GraalVM to support interoperability between any combination of languages without requiring them to know of each other. For more details, proceed to the High-Performance Cross-Language Interoperability in a Multi-Language Runtime paper.

Throughout this section you learn how to combine multiple languages using GraalVM Polyglot APIs.

Running Polyglot Applications #

The following examples are designed to get you started with a basic polyglot application. Select a section for your Start Language and then select a tab for the Target Language.

The below examples are expected to work equally from a JVM or native standalone distribution. For native launchers and native executables using Java as a Target Language and accessing classes other than Java arrays, it is required to recompile the image and provide a reflection configuration file.

Note: To start an application with LLVM as a Target Language, make sure to precompile the polyglot.c file provided below.

Start from JavaScript / Node.js #

Create the file polyglot.js:

  // BEGIN-SNIPPET
var array = Polyglot.eval("R", "c(1,2,42,4)")
console.log(array[2]);
// END-SNIPPET

  // BEGIN-SNIPPET
var array = Polyglot.eval("ruby", "[1,2,42,4]")
console.log(array[2]);
// END-SNIPPET

  // BEGIN-SNIPPET
var array = Polyglot.eval("python", "[1,2,42,4]")
console.log(array[2]);
// END-SNIPPET

  // BEGIN-SNIPPET
var array = new (Java.type("int[]"))(4);
array[2] = 42;
console.log(array[2])
// END-SNIPPET

  // BEGIN-SNIPPET
var cpart = Polyglot.evalFile("llvm", "polyglot");
cpart.main()
// END-SNIPPET

R
Ruby
Python
Java
LLVM

Target Language

Run:

js polyglot.js
42
node polyglot.js
42

Start Language R #

Create the file polyglot.R:

 
  # BEGIN-SNIPPET
array <- eval.polyglot("js", "[1,2,42,4]")
print(array[3L])
# END-SNIPPET

 
  # BEGIN-SNIPPET
array <- eval.polyglot("ruby", "[1,2,42,4]")
print(array[3L])
# END-SNIPPET

 
  # BEGIN-SNIPPET
array <- eval.polyglot("python", "[1,2,42,4]")
print(array[3L])
# END-SNIPPET

 
  # BEGIN-SNIPPET
array <- new("int[]", 4)
array[3L] <- 42
print(array[3L])
# END-SNIPPET

 
  # BEGIN-SNIPPET
cpart <- eval.polyglot("llvm", path="polyglot")
cpart$main()
# END-SNIPPET

JS
Ruby
Python
Java
LLVM

Target Language

Run:

Rscript polyglot.R
[1] 42

Start Language Ruby #

Create the file polyglot.rb:

  # BEGIN-SNIPPET
array = Polyglot.eval('js', '[1,2,42,4]')
puts array[2]
# END-SNIPPET

  # BEGIN-SNIPPET
array = Polyglot.eval('R', 'c(1L,2L,42L,4L)')
puts array[2]
# END-SNIPPET

  # BEGIN-SNIPPET
array = Polyglot.eval('python', '[1,2,42,4]')
puts array[2]
# END-SNIPPET

  # BEGIN-SNIPPET
array = Java.type('int[]').new(4)
array[2] = 42
print(array[2])
# END-SNIPPET

  # BEGIN-SNIPPET
cpart = Polyglot.eval_file('llvm', 'polyglot')
cpart.main()
# END-SNIPPET

JS
R
Python
Java
LLVM

Target Language

Run:

ruby polyglot.rb
42

Start Language Python #

Create the file polyglot.py:

  # BEGIN-SNIPPET
import polyglot
array = polyglot.eval(language="js", string="[1,2,42,4]")
print(array[2])
# END-SNIPPET

  # BEGIN-SNIPPET
import polyglot
array = polyglot.eval(language="R", string="c(1L,2L,42L,4L)")
print(array[2])
# END-SNIPPET

  # BEGIN-SNIPPET
import polyglot
array = polyglot.eval(language="ruby", string="[1,2,42,4]")
print(array[2])
# END-SNIPPET

  # BEGIN-SNIPPET
import java
array = java.type("int[]")(4)
array[2] = 42
print(array[2])
# END-SNIPPET

  # BEGIN-SNIPPET
import polyglot
cpart = polyglot.eval(language="llvm", path="polyglot")
cpart.main()
# END-SNIPPET

JS
R
Ruby
Java
LLVM

Target Language

Run:

graalpy polyglot.py
42

Start Language Java #

Create the file Polyglot.java:

  // BEGIN-SNIPPET
import org.graalvm.polyglot.*;

class Polyglot {
    public static void main(String[] args) {
        Context polyglot = Context.create();
        Value array = polyglot.eval("js", "[1,2,42,4]");
        int result = array.getArrayElement(2).asInt();
        System.out.println(result);
    }
}
// END-SNIPPET

  // BEGIN-SNIPPET
import org.graalvm.polyglot.*;

class Polyglot {
    public static void main(String[] args) {
        Context polyglot = Context.newBuilder().
    	    		               allowAllAccess(true).build();
        Value array = polyglot.eval("R", "c(1,2,42,4)");
        int result = array.getArrayElement(2).asInt();
        System.out.println(result);
    }
}
// END-SNIPPET

  // BEGIN-SNIPPET
import org.graalvm.polyglot.*;

class Polyglot {
    public static void main(String[] args) {
        Context polyglot = Context.newBuilder().
        		               allowAllAccess(true).build();
        Value array = polyglot.eval("ruby", "[1,2,42,4]");
        int result = array.getArrayElement(2).asInt();
        System.out.println(result);
    }
}
// END-SNIPPET

  // BEGIN-SNIPPET
import org.graalvm.polyglot.*;

class Polyglot {
    public static void main(String[] args) {
        Context context = Context.newBuilder().allowIO(true).build();
        Value array = context.eval("python", "[1,2,42,4]");
        int result = array.getArrayElement(2).asInt();
        System.out.println(result);
    }
}
// END-SNIPPET

  // BEGIN-SNIPPET
import java.io.*;
import org.graalvm.polyglot.*;

class Polyglot {
    public static void main(String[] args) throws IOException {
        Context polyglot = Context.newBuilder().
        		               allowAllAccess(true).build();
        File file = new File("polyglot");
        Source source = Source.newBuilder("llvm", file).build();
        Value cpart = polyglot.eval(source);
        cpart.execute();
    }
}
// END-SNIPPET

JS
R
Ruby
Python
LLVM

Target Language

Run:

javac Polyglot.java
java Polyglot
42

Start Language C #

Create the file polyglot.c:

 
  // BEGIN-SNIPPET
#include <stdio.h>
#include <graalvm/llvm/polyglot.h>

int main() {
    void *array = polyglot_eval("js", "[1,2,42,4]");
    int element = polyglot_as_i32(polyglot_get_array_element(array, 2));
    printf("%d\n", element);
    return element;
}
// END-SNIPPET

 
  // BEGIN-SNIPPET
#include <stdio.h>
#include <graalvm/llvm/polyglot.h>

int main() {
    void *array = polyglot_eval("R", "c(1,2,42,4)");
    int element = polyglot_as_i32(polyglot_get_array_element(array, 2));
    printf("%d\n", element);
    return element;
}
// END-SNIPPET

 
  // BEGIN-SNIPPET
#include <stdio.h>
#include <graalvm/llvm/polyglot.h>

int main() {
    void *array = polyglot_eval("ruby", "[1,2,42,4]");
    int element = polyglot_as_i32(polyglot_get_array_element(array, 2));
    printf("%d\n", element);
    return element;
}
// END-SNIPPET

 
  // BEGIN-SNIPPET
#include <stdio.h>
#include <graalvm/llvm/polyglot.h>

int main() {
    void *array = polyglot_eval("python", "[1,2,42,4]");
    int element = polyglot_as_i32(polyglot_get_array_element(array, 2));
    printf("%d\n", element);
    return element;
}
// END-SNIPPET

 
  // BEGIN-SNIPPET
#include <stdio.h>
#include <graalvm/llvm/polyglot.h>

int main() {
    void *arrayType = polyglot_java_type("int[]");
    void *array = polyglot_new_instance(arrayType, 4);
    polyglot_set_array_element(array, 2, 42);
    int element = polyglot_as_i32(polyglot_get_array_element(array, 2));
    printf("%d\n", element);
    return element;
}
// END-SNIPPET

JS
R
Ruby
Python
Java

Target Language

The example C code has to be compiled to LLVM bitcode using the LLVM frontend such as clang. A user can use clang from the pre-built LLVM toolchain shipped with the GraalVM LLVM runtime:

export LLVM_TOOLCHAIN=$(lli --print-toolchain-path)

Run:

$LLVM_TOOLCHAIN/clang polyglot.c -lgraalvm-llvm -o polyglot
lli polyglot
42

Polyglot Options #

You can configure a language engine for better throughput or startup.

--engine.Mode=default configures the execution mode of the engine. The execution mode automatically tunes the polyglot engine towards latency or throughput.
- throughput collects the maximum amount of profiling information and compiles using the maximum number of optimizations. This mode results in slower application startup but better throughput. This mode uses the compiler configuration community or enterprise if not specified otherwise.
- default uses a balanced engine configuration. This mode uses the compiler configuration community or enterprise if not specified otherwise.
- latency collects only minimal profiling information and compiles as fast as possible with less optimal-generated code. This mode results in faster application startup but less optimal throughput. This mode uses the compiler configuration economy if not specified otherwise.

Passing Options to Language Launchers #

Every language launcher has been extended with a set of so called polyglot options. Polyglot options allow users of any language launcher to access the options of other languages supported by GraalVM (implemented with the Truffle language implementation framework). The format is: --<languageID>.<property>=<value>. For example, the R launcher also supports the --js.atomics=true JavaScript option.

Allowed values for the languageID are:

js: options for JavaScript
python: options for Python
r: options for R
ruby: options for Ruby
llvm: options for LLVM

Use --help:languages to find out which options are available.

Options for polyglot tools work in the same way with the following format: --<toolID>.<property>=<value>.

Allowed values for <toolID> are:

inspect: allows debugging with Chrome DevTools
cpusampler: collects data about CPU usage
cputracer: captures trace information about CPU usage
memtracer: captures trace information about memory usage

Use --help:tools to find out which options are available.

Passing Options Programmatically #

Options can also be passed programmatically using the Java polyglot API.

Create a file called OptionsTest.java:

import org.graalvm.polyglot.*;

class OptionsTest {

    public static void main(String[] args) {
        Context polyglot = Context.newBuilder()
            .allowExperimentalOptions(true)
            .option("js.shared-array-buffer", "true")
            .build();
        // the use of shared array buffer requires the 'js.shared-array-buffer' option to be 'true'
        polyglot.eval("js", "new SharedArrayBuffer(1024)");
    }
}

Run:

javac OptionsTest.java
java OptionsTest

Note: Tools options can be passed in the same way. Options cannot be modified after the context was created.

Passing Options Using JVM Arguments #

Every polyglot option can also be passed as a Java system property. Each available option translates to a system property with the polyglot. prefix. For example, -Dpolyglot.js.strict=true sets the default value for a strict interpretation for all JavaScript code that runs in the JVM. Options that were set programmatically take precedence over Java system properties. For languages the following format can be used: -Dpolyglot.<languageID>.<property>=<value> and for tools it is: -Dpolyglot.<toolID>.<property>=<value>.

Create a file called SystemPropertiesTest.java:

import org.graalvm.polyglot.*;

class SystemPropertiesTest {

    public static void main(String[] args) {
        Context polyglot = Context.newBuilder()
        .allowExperimentalOptions(true)
        .build();
        // the use of shared array buffer requires the 'js.shared-array-buffer' option to be 'true'
        polyglot.eval("js", "new SharedArrayBuffer(1024)");
    }
}

Run:

javac SystemPropertiesTest.java
java -Dpolyglot.js.strict=true SystemPropertiesTest

Note: System properties are read once when the polyglot context is created. Subsequent changes have no effect.

Learn more about a guest and Java host language interoperability from the Embedding Languages documentation

Polyglot Programming

Running Polyglot Applications #

Start from JavaScript / Node.js #

Start Language R #

Start Language Ruby #

Start Language Python #

Start Language Java #

Start Language C #

Polyglot Options #

Passing Options to Language Launchers #

Passing Options Programmatically #

Passing Options Using JVM Arguments #

Related Documentation #

Connect with us