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 Path	findHome() Finds the GraalVM home folder.
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 context builder that allows to configure an engine instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, 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. The engine is constructed with the same configuration as it will be as when constructed implicitly using the context builder.

Since:

19.0

See Also:

to create a new execution context.

newBuilder

public static Engine.Builder newBuilder()

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

Since:

19.0

See Also:

to construct a new execution context.

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