Package 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

  • 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:

    • 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:

    • 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:

    • 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:

    • 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