org.graalvm.polyglot

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 and Description
class	Engine.Builder

Method Summary

Modifier and Type	Method and 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 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.

Methods inherited from class java.lang.Object

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

Method Detail

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.

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:

Engine.close(boolean), Engine.close()

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 Engine.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