Class Engine

java.lang.Object

org.graalvm.polyglot.Engine

All Implemented Interfaces:

AutoCloseable

public final class Engine
extends Object
implements AutoCloseable

An execution engine for Graal guest languages that allows to inspect the the installed guest languages, instruments and their available options.

By default every context creates its own engine instance implicitly when instantiated. Multiple contexts can use an explicit engine when using a context builder. If contexts share the same engine instance then they share instruments and their configuration.

It can be useful to create an engine instance without a context to only access meta-data for installed languages, instruments and their available options.

Since:

19.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
final class	Engine.Builder

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this engine and frees up allocated native resources.
void	close(boolean cancelIfExecuting)	Closes this engine and frees up allocated native resources.
static boolean	copyResources(Path targetFolder, String... components)	Unpacks the language or instrument internal resources specified by the components into the targetFolder directory.
static Engine	create()	Creates a new engine instance with default configuration.
static Engine	create(String... permittedLanguages)	Creates a new engine instance with default configuration with a set of permitted languages.
static Path	findHome()	Finds the GraalVM home folder.
Set<Source>	getCachedSources()	Returns the sources previously cached by this engine.
String	getImplementationName()	Gets a human-readable name of the polyglot implementation (for example, "Default Truffle Engine" or "Graal Truffle Engine").
Map<String, Instrument>	getInstruments()	Gets all installed instruments of this engine.
Map<String,Language>	getLanguages()	Gets a map of all installed languages with the language id as key and the language object as value.
OptionDescriptors	getOptions()	Returns all options available for the engine.
String	getVersion()	Gets the version string of the engine in an unspecified format.
static Engine.Builder	newBuilder()	Creates a new engine builder that allows to configure an engine instance.
static Engine.Builder	newBuilder(String... permittedLanguages)	Creates a new engine builder that allows to configure an engine instance.
boolean	storeCache(Path targetFile)	Stores the auxiliary engine cache to the targetFile without cancellation.
boolean	storeCache(Path targetFile, WordPointer cancelledWord)	Stores the auxiliary engine cache to the targetFile.

Methods inherited from class Object

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

Method Details

getLanguages

public Map<String,Language> getLanguages()

Gets a map of all installed languages with the language id as key and the language object as value. The returned map is unmodifiable and might be used from multiple threads.

Since:

19.0

getInstruments

public Map<String, Instrument> getInstruments()

Gets all installed instruments of this engine. An instrument alters and/or monitors the execution of guest language source code. Common examples for instruments are debuggers, profilers, or monitoring tools. Instruments are enabled via options passed to the engine when the engine or context is constructed.

Since:

19.0

getOptions

public OptionDescriptors getOptions()

Returns all options available for the engine. The engine offers options with the following groups:

• engine: options to configure the behavior of this engine.
• compiler: options to configure the behavior of the compiler.

The language and instrument specific options need to be retrieved using Instrument.getOptions() or Language.getOptions().

Since:

19.0

See Also:

• To get a list of options for a language.
• To get a list of options for an instrument.
• To set an option for an engine, language, or instrument.
• To set an option for a context.

getVersion

public String getVersion()

Gets the version string of the engine in an unspecified format.

Since:

19.0

close

public void close(boolean cancelIfExecuting)

Closes this engine and frees up allocated native resources. If there are still open context instances that were created using this engine and they are currently not being executed then they will be closed automatically. If an attempt to close an engine was successful then consecutive calls to close have no effect. If a context is cancelled then the currently executing thread will throw a PolyglotException. The exception indicates that it was cancelled.

Parameters:

cancelIfExecuting - if true then currently executing contexts will be cancelled, else an IllegalStateException is thrown.

Since:

19.0

close

public void close()

Closes this engine and frees up allocated native resources. If there are still open context instances that were created using this engine and they are currently not being executed then they will be closed automatically. If an attempt to close the engine was successful then consecutive calls to close have no effect.

Specified by:

close in interface AutoCloseable

Throws:

IllegalStateException - if there currently executing open context instances.

Since:

19.0

See Also:

• close(boolean)
• close()

storeCache

public boolean storeCache(Path targetFile)
                   throws UnsupportedOperationException

Stores the auxiliary engine cache to the targetFile without cancellation.

Throws:

UnsupportedOperationException - if this engine or the host virtual machine does not support storing the cache.

Since:

25.0

See Also:

• storeCache(Path, WordPointer)

storeCache

public boolean storeCache(Path targetFile,
 WordPointer cancelledWord)
                   throws CancellationException,
UnsupportedOperationException

Stores the auxiliary engine cache to the targetFile. If it already exists, the file will be overwritten. The option engine.CacheStoreEnabled must be set to true to use this feature. Stored caches may be loaded by specifying the path using the engine.CacheLoad option.

Note that this feature is experimental and only supported on native-image hosts with Truffle's enterprise extensions.

Basic Usage:

// Store the engine cache into a file
Path store = Files.createTempFile("cache", "engine");
try (Engine e = Engine.newBuilder().allowExperimentalOptions(true).option("engine.CacheStoreEnabled", "true").build()) {
    try (Context c = Context.newBuilder().engine(e).build()) {
        // Evaluate sources, run application
    }
    e.storeCache(store);
}

// Load the engine cache from a file
try (Engine e = Engine.newBuilder().allowExperimentalOptions(true).option("engine.CacheLoad", store.toAbsolutePath().toString()).build()) {
    try (Context c = Context.newBuilder().engine(e).build()) {
        // The context should be able to use
        // the existing code cache.
    }
}

See the documentation on auxiliary engine caching for further details.

Parameters:

targetFile - the file to which the cache is stored

cancelledWord - a native pointer; if set to a non-zero value, the operation is cancelled. Allows cancellation of the cache store operation through a cancelled control word. The memory address pointing to the control word is polled periodically during storage without guaranteed frequency and may be delayed by safepoints such as garbage collection. A control word value of zero must be maintained for the duration of the operation. If a non-zero value is detected, the operation will be cancelled. A non-null provided pointer must remain accessible during the entire operation. Providing an invalid or inaccessible pointer may result in a VM crash.

Returns:

true if the file was written; otherwise, false

Throws:

CancellationException - if the storeCache operation was cancelled via the cancelled pointer

UnsupportedOperationException - if this engine or host virtual machine does not support cache storage

Since:

25.0

getImplementationName

public String getImplementationName()

Gets a human-readable name of the polyglot implementation (for example, "Default Truffle Engine" or "Graal Truffle Engine"). The returned value may change without notice. The value is never null.

Since:

19.0

create

public static Engine create()

Creates a new engine instance with default configuration. This method is a shortcut for newBuilder().build().

Since:

19.0

See Also:

• to create a new execution context.

create

public static Engine create(String... permittedLanguages)

Creates a new engine instance with default configuration with a set of permitted languages. This method is a shortcut for newBuilder(permittedLanuages).build().

Since:

21.3

See Also:

• to create a new execution context.

newBuilder

public static Engine.Builder newBuilder()

Creates a new engine builder that allows to configure an engine instance. This method is equivalent to calling newBuilder(String...) with an empty set of permitted languages.

Since:

21.3

newBuilder

public static Engine.Builder newBuilder(String... permittedLanguages)

Creates a new engine builder that allows to configure an engine instance.

Parameters:

permittedLanguages - names of languages permitted in the engine. If no languages are provided, then all installed languages will be permitted. All contexts created with this engine will inherit the set of permitted languages.

Returns:

a builder that can create a context

Since:

21.3

findHome

public static Path findHome()

Finds the GraalVM home folder. This is equivalent to HomeFinder.getHomeFolder() which should be preferred.

Returns:

the path to a folder containing the GraalVM or null if it cannot be found

Since:

19.0

getCachedSources

public Set<Source> getCachedSources()

Returns the sources previously cached by this engine. Only sources may be returned that allow caching (default on). The source cache of the engine is using weak references to refer to the source objects. Calling this method will result in a strong reference to all cached sources of this engine until the returned set is no longer referenced. This method is useful to find out which sources very already evaluated by this engine. This method only returns sources that were evaluated using Context.eval(Source). Sources evaluated by the guest application will not be returned. The return set is never null and not modifiable.

Since:

20.3

copyResources

public static boolean copyResources(Path targetFolder,
 String... components)
                             throws IOException

Unpacks the language or instrument internal resources specified by the components into the targetFolder directory.

During execution, the internal resource cache location can be overridden by the following system properties:

• polyglot.engine.resourcePath: Sets the cache location to the given path. The expected folder structure is the structure generated by this method.
• polyglot.engine.resourcePath.<component>: Retains the default cache folder but overrides caches for the specified component with the given path. The expected folder structure is targetFolder/<component>.
• polyglot.engine.resourcePath.<component>.<resource-id> : Retains the default cache folder but overrides caches for the specified resource within the component with the given path. The expected folder structure is targetFolder/<component>/<resource-id>.

Parameters:

targetFolder - the folder to unpack resources into

components - names of languages or instruments whose resources should be unpacked. If no languages or instruments are provided, then all installed languages and instruments are used

Returns:

true if at least one of the components has associated resources that were unpacked into targetFolder

Throws:

IllegalArgumentException - if the components list contains an id of a language or instrument that is not installed

IOException - in case of an IO error

Since:

23.1