This changelog summarizes major changes between GraalVM SDK versions. The main focus is on APIs exported by GraalVM SDK.
- GR-60636 Truffle now stops compiling when the code cache fills up on HotSpot. A warning is printed when that happens.
- GR-54905 When using Truffle NFI with the Panama backend, native access must now be granted to the Truffle module instead of the NFI Panama module. Use the
--enable-native-access=org.graalvm.truffle
Java command line option to enable the native access for the NFI Panama backend. - GR-57681 Added the ability to use
Value#as(byte[].class)
to copy the contents of a guest language byte buffer (Value#hasBufferElements()
) to a new byte array. The new functionality has precedence over accessing the guest object as array (Value#hasArrayElements()
) if both ways are available. - GR-57817 Starting with JDK 24 users now need to configure native access privileges to the java executable in order to avoid warnings from being printed by the JDK.
For usages of the module-path pass the
--enable-native-access=org.graalvm.truffle
option and for class-path usages pass the--enable-native-access=ALL-UNNAMED
option to resolve the new warning. Note that Truffle automatically forwards the native access capability to all loaded languages and tools, therefore no further configuration is required. If the native access is denied by the user with--illegal-native-access=deny
then loading the optimizing runtime will fail and the fallback runtime will be used. More information can be found in the integrity-by-default JEP-472. - GR-54300
Context
andEngine
is now automatically closed when no longer strongly referenced. A reachableValue
orPolyglotException
will keep the associatedContext
reachable. Additionally, theContext
remains reachable when explicitly entered or if there is an active polyglot thread within it. TheEngine
remains reachable when there is a strongly reachableLanguage
,Instrument
, orContext
instance. However, it is still recommended not to rely on garbage collection for closing. Instead, use the try-with-resources pattern for explicit context and engine management. For more information, refer to the Automatic Close on GC documentation. - GR-60022 Introduced the FileSystem.newCompositeFileSystem method, which creates a composite
FileSystem
delegating operations to the specified delegate FileSystem instances based on the provided selectors. - GR-60022 Introduced the FileSystem.newDenyIOFileSystem method, which creates a
FileSystem
that denies all file operations except for path parsing. - GR-57838 Added automatic inclusion of language and instrument resources for embedding Truffle languages in native image. We no longer produce a resources folder next to the image by default. Documentation available here.
- GR-51177 Enable random offsets of runtime compiled function entry points for the UNTRUSTED polyglot sandbox policy.
- GR-51962 Added the system property
polyglot.engine.userResourceCache
, which enables embedders to override the default location of the resources cache folder for polyglot applications running on the JVM. By default, the resources cache folder is located in theorg.graalvm.polyglot
directory within the OS specific cache folder in the user's home directory. The main rationale behind this override is to accommodate applications running in containers where the user's home directory may not be writable. - GR-51402 Improved Polyglot guest function to host interface proxies to infer the expected return type from the corresponding type argument (
R
) of the generic target type (e.g.BiFunction<T,U,R>
). - GR-53699
RuntimeOptions.listDescriptors
andgetDescriptor
also returns graal compiler options (if any) that could already be accessed throughRuntimeOptions.get
andset
. - GR-54310 Removed disabled-by-default class-path isolation feature if polyglot is used from the class-path. The option
-Dpolyglotimpl.DisableClassPathIsolation
has no longer any effect. - GR-49484 Added
PolyglotException.StackFrame.getBytecodeIndex()
which allows to access the internal bytecode index that the language uses to identify an execution location. - GR-47956 Added the option
engine.InterpreterCallStackHeadRoom
to protect against stack overflow in the middle of a guest method execution in the interpreter. The new option is available only in the AOT mode. - GR-40931 Added experimental support for virtual threads on HotSpot. Not all languages are currently supported for use with virtual threads, please check the language changelog for further information. Truffle debugging, CPU time limits and some memory limits are currently not supported on virtual threads.
- GR-40931 Using virtual threads in a native-image will now emulate virtual threads using platform threads until Loom support for Truffle languages in native-image is implemented.
- GR-48481: It is now possible to depend on platform-specific Maven artifacts when using polyglot isolates. The
-isolate
Maven artifacts remain platform-independent. However, if platform specific builds are required, consider adding a platform specific suffix to the Maven artifact name, such as-isolate-linux-amd64
. The reduced binary size of platform specific dependencies can improve build times and reduce the distribution size of your application. For more details, see Embedding Languages. - GR-48481: The Python language is now available as a polyglot isolate.
- GR-54674: Added the options
engine.TraceSourceCache
andengine.TraceSourceCacheDetails
to allow tracing of source cache hits, misses, failures and evictions.
- (GR-49334) Deprecated the
FileSystems#allowLanguageHomeAccess()
method and introducedFileSystem#allowInternalResourceAccess()
as a replacement. To ensure compatibility, both methods now provide support for language homes and internal resources. - (GR-49386) Added
Value#readBuffer(long, byte[], int, int)
to enable bulk reads of buffers into byte arrays. - (GR-49386) Added the ability to use
Value#as(ByteSequence.class)
to map guest language byte buffers (Value#hasBufferElements()
) to the read-onlyByteSequence
interface in order to access the bytes without copying the guest language buffer. - (GR-49386) Custom implementations of
ByteSequence
, like the values returned byByteSequence.create(byte[])
, are now interpreted by guest languages as buffers. - (GR-38404) Added the ability to use
Value#as(Collection.class)
to map guest language arrays (Value#hasArrayElements()
) to theCollection
interface in order to access the array elements without copying the guest language array. - (GR-50682) The Truffle languages and instrument implementations are now loaded exclusively using the context class loader if it is set and Truffle is found there. If the context class loader is not set or Truffle is not found, then the system class loader is used instead. Previously, the context and system class loader were used to load Truffle languages and instruments which causes issues if the context class loader does not delegate to the system class loader and classes are loaded from both. Context class loaders that do not delegate to the system class loader are commonly used to implement hot-reload functionality.
- (GR-43819) The GraalVM SDK was split into several more fine-grained modules. The use of the graalvm-sdk module is now deprecated. Please update your Maven and module dependencies accordingly. Note that all APIs remain compatible. The following new modules are available:
org.graalvm.nativeimage
A framework that allows to customize native image generation.- `org.graalvm.polyglot´: A framework that allows to embed polyglot language implementations in Java.
org.graalvm.word
: A low-level framework for machine-word-sized values in Java.org.graalvm.collections
: A collections framework for GraalVM components. Old Maven configuration:
New Maven configuration:<dependency> <groupId>org.graalvm.sdk</groupId> <artifactId>graal-sdk</artifactId> <version>${graalvm.version}</version> </dependency>
<dependency> <groupId>org.graalvm.sdk</groupId> <artifactId>nativeimage</artifactId> <version>${graalvm.version}</version> </dependency> <dependency> <groupId>org.graalvm.polyglot</groupId> <artifactId>polyglot</artifactId> <version>${graalvm.version}</version> </dependency> <dependency> <groupId>org.graalvm.sdk</groupId> <artifactId>word</artifactId> <version>${graalvm.version}</version> </dependency> <dependency> <groupId>org.graalvm.sdk</groupId> <artifactId>collections</artifactId> <version>${graalvm.version}</version> </dependency>
- (GR-43819) The
org.graalvm.polyglot
package and module is no longer contained in the boot module of a GraalVM JDK. Please depend onorg.graalvm.polyglot:polyglot
using Maven instead. - (GR-47917) Added class-path isolation if polyglot is used from the class-path. At class initialization time and if polyglot is used from the class-path then the polyglot implementation spawns a module class loader with the polyglot runtime and language implementations. This allows to use an optimized runtime even if languages and polyglot are used from the class-path. Note that for best performance, it is recommended to load polyglot and the languages from the module-path.
- (GR-43819) Removed the deprecated APIs in
org.graalvm.nativeimage.RuntimeOptions
and added a new replacement API. - (GR-46556) Provide documentation and example code on how to use Truffle languages via the ScriptEngine API. The example code can be inlined and modified for testing, we still recommend to use the Polyglot API for full control over embeddings.
- (GR-45896) JLine3 upgrade from 3.16 to 3.23. The JLine3 bundle that is used is customized and contains only
jline3-reader
,jline3-terminal
, andjline3-builtins
JLine3 components. - (GR-44222) Polyglot contexts and engines now print a warning when deprecated options were used. To resolve this migrate the option using the deprecation instructions or set the
engine.WarnOptionDeprecation
tofalse
to suppress this warning. It is recommended to prefer migration over suppression whenever possible. - (GR-46345) Added
Engine#copyResources(Path, String...)
to unpack the specified language and instrument resources into the target directory. This method is designed for creating pre-built installations of internal resources, specifically for standalone applications. - (GR-36213) Added
HostAccess.Builder#useModuleLookup(Lookup)
to allow guest applications to access host classes from named modules. PassingMethodHandles#lookup()
from a named module is the intended usage. - (GR-48133) Native Image API: Added ability to promote jars from the class-path to the module-path in the native image driver. Use
ForceOnModulePath = ${module-name}
. Promoting a module to the module-path is equivalent to specifying it on the module-path in combination with exporting the module using--add-modules ${module-name}
to the unnamed module.
- (GR-26758) Added the TraceLimits option to the Truffle Sandbox to measure a guest application's resource consumption and obtain realistic sandbox parameters.
- (GR-25849) (GR-41634) Added a new way to configure the IO access using the new class
IOAccess
. The IO access configuration determines how a guest language can access the host IO. TheIOAccess
class provides a predefined configuration to disable host IO access, or to enable full host IO access. A custom configuration can be created using an IOAccess builder. - Deprecated
Context.Builder#allowIO(boolean)
To migrate, usebuilder.allowIO(IOAccess.ALL)
to enable unrestricted IO operations on the host system, orbuilder.allowIO(IOAccess.NONE)
to disable IO operations. - Deprecated
Context.Builder#fileSystem(FileSystem)
. To migrate, usebuilder.allowIO(IOAccess.newBuilder().fileSystem(fileSystem).build())
. - Added automatic copying of language resources for embedding Truffle languages in native image. Documentation available here.
- (GR-41716) Added
HostAccess.Builder.allowMutableTargetMappings(HostAccess.MutableTargetMapping[])
to explicitly enable type coercion from guest objects to mutable Java host objects such asjava.util.Map
orjava.util.List
. - (GR-42876) Added FileSystem#newFileSystem creating a polyglot FileSystem for given Java NIO FileSystem.
- (GR-43820) Deprecated
org.graalvm.nativeimage.RuntimeOptions#getOptions
methods andorg.graalvm.nativeimage.RuntimeOptions.OptionClass
enum. These elements were mistakenly made API and will be removed in a future version. If your codebase depends on any of these please let us know. - (GR-43997) Introduced the
LockFreePool
concurrent collection, and change theLockFreePrefixTree
API to allow custom allocation policies. - (GR-25539) Added
Value#fitsInBigInteger()
andValue#asBigInteger()
to access guest or host number values that fit intojava.math.BigInteger
without loss of precision.Value.as(BigInteger.class)
is also supported for such values. - (GR-25539) (potentially breaking-change) By default, all host values of type
java.lang.BigInteger
will now be interpreted as number values (Value.isNumber()
). Previously, they were not interpreted as numbers. In order to restore the old behavior setHostAccess.Builder.allowBigIntegerNumberAccess(boolean)
to false. Note that language support for interpreting numbers that do not fit into long values may vary. Some languages, like JavaScript, may require explicit conversions of host big integers. Other languages, like Ruby or Python can use big integers without explicit conversion. The same applies to values passed across guest languages. - (GR-30473) Added the SandboxPolicy that presets and validates context or engine configurations to make them suitable as a code sandbox. The policy is set by passing it to the Engine.Builder#sandbox(SandboxPolicy) or Context.Builder#sandbox(SandboxPolicy) builder method.
- (GR-30473) For each SandboxPolicy a predefined host access policy was added:
- CONSTRAINED satisfies the
SandboxPolicy#CONSTRAINED
requirements. This host access is the default value for a Context withSandboxPolicy#CONSTRAINED
. - ISOLATED satisfies the
SandboxPolicy#ISOLATED
requirements. This host access is the default value for a Context withSandboxPolicy#ISOLATED
. - UNTRUSTED satisfies the
SandboxPolicy#UNTRUSTED
requirements. This host access is the default value for a Context withSandboxPolicy#UNTRUSTED
.
- CONSTRAINED satisfies the
- (GR-39852) Native Image API: Added FieldValueTransformer API
- (GR-35358) Added
Context.Builder.allowInnerContextOptions(boolean)
which allows the context to spawn inner contexts and modify and override language options. The default value for this privilege is set dependingContext.Builder.allowAllPrivilages(boolean)
is set or not. Do not enable this privilege in security sensitive scenarios. - (GR-40198) Introduce public API for programmatic JNI / Resource / Proxy / Serialization registration from Feature classes during the image build.
- (GR-38909) Added Native Image com.oracle.svm.core.annotate annotation classes (@Alias, @TargetClass, @Substitute, ...).
- (GR-38925) Added
Value.hasMetaParents() and Value.getMetaParents()
that allow lookup of the hierarchy of parents for meta objects (e.g. super class or implemented interface of Java classes). - (GR-38351) Added FileSystem#allowLanguageHomeAccess returning a
FileSystem
that forwards access to files in the language home to the default file system. - (GR-38351) Added FileSystem#newReadOnlyFileSystem returning a read-only decorator for the given file system.
- Changed the behavior of
Context.close()
(as well asContext.close(false)
which is equivalent). In case the context was cancelled during the close operation or the context was exited during the close operation at request of the guest application, or it was already cancelled or exited before the close operation begins, the close operation throws aPolyglotException
withPolyglotException.isCancelled()
orPolyglotException.isExit()
, respectively, equal totrue
. - (GR-29138)(EE-only) Added the ability to spawn a native-image isolate for a each
Engine
orContext
in a native launcher or library. This feature was previously supported only for the JVM deployment (GR-22699). - Added HostAccess.Builder.allowAccessInheritance to inherit access to methods that have been explicitly exported in an interface or superclass vs. only explicitly vetted method implementations (e.g. via
@HostAccess.Export
). - Made
HostAccess.Builder.allowAccessInheritance(false)
the default. This restricts the set of accessible methods and might break existing code. To restore the previous behavior ofHostAccess.EXPLICIT
, you can useHostAccess.newBuilder(HostAccess.EXPLICIT).allowAccessInheritance(true).build()
. - Added List#add support for polyglot values that are mapped to java.util.List.
- Changed the default
Object
target type mapping (Value.as(Object.class)
) for values that have both array elements and members fromMap
toList
. Note: This is an incompatible change. Embedders relying on the dynamic typeMap
after aObject
target type coercion will have to migrate their code. The previous behavior can be restored using a custom target type mapping, e.g.:HostAccess access = HostAccess.newBuilder(HostAccess.EXPLICIT) .targetTypeMapping(Value.class, Object.class, v -> v.hasMembers() && v.hasArrayElements(), v -> v.as(Map.class)) .build(); try (Context c = Context.newBuilder().hostAccess(access).build()) { // run application }
- (GR-35010) Added API for Truffle Languages (
Language#getWebsite()
) and Instruments (Instrument#getWebsite()
) to provide website information. - (GR-33851) Dropped Java 8 support.
- (GR-31170) Native Image API: Added
WINDOWS_AARCH64
Platform. - (GR-33657) Native Image API: Added
CEntryPoint#include
attribute which can be used to controll if the entry point should be automatically added to the shared library. - (GR-22699)(EE-only) Added the ability to spawn a native-image isolate for a each
Engine
orContext
by callingContext.Builder.option("engine.SpawnIsolate", "true")
. This enables heap isolation between the host and guest applications. Using isolates improves security, startup and warmup time of polyglot languages. In this mode, calls between host and guest are more costly as they need to cross a native boundary. It is recommended to use theHostAccess.SCOPED
policy with this mode to avoid strong cyclic references between host and guest. This mode is experimental in this release and only supported for a limited set of languages.
- Added the ability to share values between contexts. Please see
Context.Builder.allowValueSharing(boolean)
for further details. - (GR-20286) Polyglot API: Added support for scoped values in guest-to-host callbacks. Scoped values are automatically released when the callback returns. They can be configured in
HostAccess
.
-
AllowVMInspection
is enabled in the native launchers,SIGQUIT
can be used to generate thread dumps. Performance counters are disabled by default, they can be enabled in the graalvm enterprise by the--vm.XX:+UsePerfData
option. -
Changed behavior of
Value.as(TypeLiteral<Function<Object, Object>>).apply()
: When the function is called with anObject[]
argument, it is passed through as a single argument rather than an array of arguments. -
Updated the required JVMCI version for Polyglot Embeddings in this release. All GraalVM JDK versions (8, 11, 16) already contain the updated JVMCI version and there is no further action required. If you are using a different JDK than GraalVM and you have configured the Graal compiler on the upgrade module path you will need one of the following JDK versions that include JDK-8264016 for full compatibility:
- Other JDK 11: Oracle JDK 11.0.13 (2021-10-19), OpenJDK is still to be determined.
- Other JDK 16: No current plans to update JVMCI.
- Other JDK 17: The new JVMCI version is already integrated into early access builds.
If your JVMCI version is outdated you will be able to use GraalVM embeddings, but forced context cancellation (
Context.close(true)
) and interrupt (Context.interrupt(Duration)
) will throw an error. We recommend the following workarounds:- Do not use forced context cancellation or interrupt. All other features are still supported.
- Switch to the fallback runtime by removing graal.jar from the upgrade-module-path. Note that this will significantly worsen performance and should only be a last resort.
- Wait with upgrading to 21.2 until the JDK version has support for the new JVMCI version.
- Added new methods in
Value
for interacting with buffer-like objects:- Added
Value.hasBufferElements()
that returnstrue
if this object supports buffer messages. - Added
Value.isBufferWritable()
that returnstrue
if this object supports writing buffer elements. - Added
Value.getBufferSize()
to return the size of this buffer. - Added
Value.readBufferByte(long)
,Value.readBufferShort(ByteOrder, long)
,Value.readBufferInt(ByteOrder, long)
,Value.readBufferLong(ByteOrder, long)
,Value.readBufferFloat(ByteOrder, long)
andValue.readBufferDouble(ByteOrder, long)
to read a primitive from this buffer at the given index. - Added
Value.writeBufferByte(long, byte)
,Value.writeBufferShort(ByteOrder, long, short)
,Value.writeBufferInt(ByteOrder, long, int)
,Value.writeBufferLong(ByteOrder, long, long)
,Value.writeBufferFloat(ByteOrder, long, float)
andValue.writeBufferDouble(ByteOrder, long, double)
to write a primitive in this buffer at the given index (supported only ifValue.isBufferWritable()
returnstrue
).
- Added
- Added
Value
methods supporting iterables and iterators:- Added
hasIterator()
specifying that theValue
is an iterable. - Added
getIterator()
to return the iterator for an iterableValue
. - Added
isIterator()
specifying that theValue
is an iterator. - Added
hasIteratorNextElement()
to test that the iteratorValue
has more elements to return by calling thegetIteratorNextElement()
method. - Added
getIteratorNextElement()
to return the current iterator element.
- Added
- Added
HostAccess.Builder.allowIterableAccess()
to allow the guest application to access JavaIterables
as values with iterators (true by default forHostAccess.ALL
andHostAccess.Builder.allowListAccess(true)
, false otherwise). - Added
HostAccess.Builder.allowIteratorAccess()
to allow the guest application to access JavaIterators
(true by default forHostAccess.ALL
,HostAccess.Builder.allowListAccess(true)
andHostAccess.Builder.allowIterableAccess(true)
, false otherwise). - Added
ProxyIterable
andProxyIterator
to proxy iterable and iterator guest values. - Added
Value
methods supporting hash maps:- Added
hasHashEntries()
specifying that theValue
provides hash entries. - Added
getHashSize()
to return hash entries count. - Added
hasHashEntry(Object)
specifying that the mapping for the specified key exists. - Added
getHashValue(Object)
returning the value for the specified key. - Added
getHashValueOrDefault(Object, Object)
returning the value for the specified key or a default value if the mapping for given key does not exist. - Added
putHashEntry(Object, Object)
associating the specified value with the specified key. - Added
removeHashEntry(Object)
removing the mapping for a given key. - Added
getHashEntriesIterator()
returning a hash entries iterator. - Added
getHashKeysIterator()
returning a hash keys iterator. - Added
getHashValuesIterator()
returning a hash values iterator.
- Added
- Added
HostAccess.Builder.allowMapAccess(boolean)
to allow the guest application to access JavaMap
as values with hash entries (true by default forHostAccess.ALL
, false otherwise). - Added
ProxyHashMap
to proxy map guest values. - When
HostAccess.Builder.allowMapAccess(boolean)
is enabled the JavaHashMap.Entry
is interpreted as a guest value with two array elements. - Added
Context.safepoint()
to manually poll thread local of a polyglot context while a host method is executed. For example, this allows the context to check for potential interruption or cancellation. Value.putMember(String, Object)
now throwsUnsupportedOperationException
instead ofIllegalArgumentException
if the member is not writable.Value.removeMember(String)
now throwsUnsupportedOperationException
instead of returningfalse
if the member is not removable.Value.invokeMember(String, Object...)
now throwsUnsupportedOperationException
instead ofIllegalArgumentException
if the member is not invokable.
- Added support for explicitly selecting a host method overload using the signature in the form of comma-separated fully qualified parameter type names enclosed by parentheses (e.g.
methodName(f.q.TypeName,java.lang.String,int,int[])
). - Deprecated host method selection by JNI mangled signature, replaced by the aforementioned new form. Scheduled for removal in 21.2.
- Added a
log.file
option that allows redirection of all language, instrument or engine logging to a file. The handler configured with theContext.Builder.logHandler
method has precedence over the new option. - The option
-Dgraal.LogFile
is no longer inherited by the polyglot engine. Use thelog.file
option or configure a log handler instead. - In host interop,
null
now adheres to Java semantics:- (Host interop's)
null
has no meta-object (e.g.Value.getMetaObject()
returnsnull
) Value.isMetaInstance(Object)
behaves likeinstanceof
with respect tonull
(e.g.null
is NOT an instance of any meta-object)
- (Host interop's)
- Removed handling of
--jvm.*
and--native.*
launcher options, which were deprecated since 1.0.0 RC14. - Added the ability to specify a
TargetMappingPrecedence
of target type mappings forHostAccess
configurations that influence conversion order and precedence in relation to default mappings and other target type mappings. - Added
PolyglotException.isInterrupted()
to determine if an error was caused by an interruption of an application thread. The interrupted exceptions are no longerPolyglotException.isCancelled()
butPolyglotException.isInterrupted()
. - All Truffle Graal runtime options (-Dgraal.) which were deprecated in GraalVM 20.1 are removed. The Truffle runtime options are no longer specified as Graal options (-Dgraal.). The Graal options must be replaced by corresponding engine options specified using polyglot API.
- Added
Engine.getCachedSources()
to return the sources that were previously cached by the engine. - Added support a default
OptionType
for Java enums.OptionType.defaultType(Class<?>)
is now always supported forenum
classes. - Added
Context.interrupt(Duration)
to interrupt a polyglot Context execution. The interrupt is non-destructive meaning that the polyglot Context can still be used for further execution. - Added
Value.as(Class)
support for converting values to abstract host classes with a default constructor. - Added
HostAccess.Builder.allowAllClassImplementations
to allow converting values to abstract host classes usingValue.as
and host interop (true by default forHostAccess.ALL
, false otherwise).
- Added
-Dpolyglot.engine.AllowExperimentalOptions=true
to allow experimental options for all polyglot engines of a host VM. This system property is intended to be used for testing only and should not be enabled in production environments. - Added a factory method creating a FileSystem based on the host Java NIO. The obtained instance can be used as a delegate in a decorating filesystem.
- Added
PolyglotException.isResourceExhausted()
to determine if an error was caused by a resource limit (e.g. OutOfMemoryError) that was exceeded. - Added
Context.parse(Source)
to parse but not evaluate a source. Parsing a source allows to trigger e.g. syntax validation prior to executing the code. - Added optional FileSystem.isSameFile method testing if the given paths refer to the same physical file. The method can be overridden by the
FileSystem
implementer with a more efficient test. - Added
EconomicMap.putIfAbsent(K, V)
to associate a value with the specified key if not already present in the map.
- The
PerformanceWarningsAreFatal
andTracePerformanceWarnings
engine options take a comma separated list of performance warning types. Allowed warning types arecall
to enable virtual call warnings,instanceof
to enable virtual instance of warnings andstore
to enables virtual store warnings. There are alsoall
andnone
types to enable (disable) all performance warnings. - The
<language-id>.home
system property that can be used in some development scenarios to specify a language's directory is deprecated. Theorg.graalvm.language.<language-uid>.home
property should be used instead. Setting this new system property is reflected by theHomeFinder
API. - Added
CompilationFailureAction
engine option which deprecatesCompilationExceptionsArePrinted
,CompilationExceptionsAreThrown
,CompilationExceptionsAreFatal
andPerformanceWarningsAreFatal
options. - Added
TreatPerformanceWarningsAsErrors
engine option which deprecates thePerformanceWarningsAreFatal
option. To replace thePerformanceWarningsAreFatal
option use theTreatPerformanceWarningsAsErrors
withCompilationFailureAction
set toExitVM
. - Added
bailout
into performance warning kinds used byTracePerformanceWarnings
,PerformanceWarningsAreFatal
andCompilationExceptionsAreFatal
options. - Added OptionDescriptor.getDeprecationMessage returning the option deprecation reason. Added OptionDescriptor.Builder.deprecationMessage() to set the option deprecation reason.
- Added
Value.isMetaObject()
,Value.getMetaQualifiedName()
,Value.getMetaSimpleName()
andValue.isMetaInstance(Object)
to allow language agnostic access to meta-objects like classes or types. - The result of
Value.getMetaObject()
will now return always meta-objects. It is recommended but not required to change uses of meta-objects to useValue.getMetaQualifiedName()
instead ofValue.toString()
to return a type name. - Added Context.Builder.hostClassLoader to allow an embedder to specify a context ClassLoader for code execution.
- The deprecated
graalvm.home
andgraalvm.version
system properties have been removed, use the HomeFinder instead. - Added
EventContext.createError
which allows to introduce guest application errors in execution listeners/nodes. - Deprecated
Instrumenter.attachExecutionEventListener
andExecutionEventListener.onInputValue
as explicit input filters are not supported by event listeners. Use ExecutionEventNodes instead. - Added Context.Builder.currentWorkingDirectory to set the current working directory used by the guest application to resolve relative paths.
- The algorithm used to generate a unique URI for a
Source
built without anURI
was changed to SHA-256. - All Truffle Graal runtime options (-Dgraal.) will be deprecated with 20.1. The Truffle runtime options are no longer specified as Graal options (-Dgraal.). The Graal options must be replaced by corresponding engine options specified using polyglot API. The
TRUFFLE_STRICT_OPTION_DEPRECATION
environment variable can be used to detect usages of deprecated Graal options. When theTRUFFLE_STRICT_OPTION_DEPRECATION
is set totrue
and the deprecated Graal option is used the engine throws aPolyglotException
listing the used deprecated options and corresponding replacements.
- The default temporary directory can be configured by FileSystem.
- Added
org.graalvm.polyglot.ResourceLimits
that allows to specify context specific time and statement count execution limits. - Added HomeFinder, a utility class to find various paths of the running GraalVM.
- Contexts can now be closed if they are still explicitly entered using
Context.enter
on the current thread. This allows for simpler error recovery code. - Added
Value.getContext()
to access the context a value is associated with. - Added
org.graalvm.home.Version
version utility that allows to create, validate and compare GraalVM versions. - Added Value API methods for interacting with exception objects: Value#isException and Value#throwException.
- Added target type mapping from exception objects to PolyglotException.
- Added support for date, time, timezone and duration values in polyglot
- Added methods to identify polyglot date, time, timezone and duration values in
Value
. SeeValue.isDate
,Value.isTime
,Value.isTimeZone
,Value.isDuration
. - Polyglot languages now interpret the
java.time
host values of typeLocalDate
,LocalTime
,LocalDateTime
,ZonedDateTime
,Instant
,ZoneId
andDuration
. They are mapped to the appropriate guest language types. - Added
ProxyDate
,ProxyTime
,ProxyTimeZone
,ProxyInstant
andProxyDuration
to proxy date time and duration related guest values.
- Added methods to identify polyglot date, time, timezone and duration values in
- Added
Context.Builder.timeZone(ZoneId)
to configure the default timezone of polyglot contexts. - Added OptionKey.mapOf to group/accumulate key=value pairs for options whose keys are not known beforehand e.g. user-defined properties.
- Added ability to configure custom polyglot access configuration with
PolyglotAccess.newBuilder()
. It allows to configure fine-grained access control for polyglot bindings and between polyglot languages.
- Restricting guest languages from sub-process creation by Context.Builder.allowCreateProcess. Use
Context.newBuilder().allowCreateProcess(true)
to allow guest languages to create a new sub-process. - Added a possibility to control sub-process creation using a custom ProcessHandler implementation. Use
Context.newBuilder().processHandler(handler)
to install a customProcessHandler
. - Restricting access to the host environment variables via EnvironmentAccess configurations. Use
EnvironmentAccess.INHERIT
to allow guest languages to read process environment variables. - Deprecated
OptionValues#set
, OptionValues should be read-only. If the value needs to be changed, it can be stored in the language or instrument and read from there. - Removed deprecated
OptionCategory.DEBUG
(useOptionCategory.INTERNAL
instead). - The path separator can now be configured by FileSystem.
Value.as(Interface.class)
now requires interface classes to be annotated withHostAccess.Implementable
inEXPLICIT
host access mode. Added new APIs to configure implementable behavior in HostAccess.
--experimental-options
can now also be passed after polyglot options on the command line.--version
changed default message toIMPLEMENTATION-NAME (ENGINE-NAME GRAALVM-VERSION)
- Renamed 'Graal SDK' to 'GraalVM SDK'
- Added optional FileSystem.getMimeType and FileSystem.getEncoding methods. These methods can be used by
FileSystem
implementer to provide file MIME type and encoding. - Added a possibility to set an encoding in Source builder
- (incompatible change) Restricting access to the host language via HostAccess configurations. Use
Context.newBuilder().allowHostAccess(HostAccess.ALL)
to get previous behavior. Configurations that useallowAllAccess(true)
are not affected by this incompatible change. - Deprecated
Context.Builder.hostClassFilter
and added the new methodContext.Builder.allowHostClassLookup
as a replacement. The name was changed for clarity and now also acceptsnull
to indicate that no host class lookup is allowed. - (incompatible change) Restricting polyglot access for guest languages via PolyglotAccess configurations. Use
Context.newBuilder().allowPolyglotAccess(PolyglotAccess.ALL)
to get previous behavior. Configurations that useallowAllAccess(true)
are not affected by this incompatible change. - Removed deprecated API class
ProxyPrimitive
. - Started adding several options under
--engine
like--engine.TraceCompilation
, which can also be set on theEngine
. These options will progressively replace the-Dgraal.*Truffle*
properties. The list can be seen by passing--help:expert
to any language launcher. - Experimental options now require
--experimental-options
on the command line to be passed to GraalVM language launchers, or Context.Builder#allowExperimentalOptions and Engine.Builder#allowExperimentalOptions to be set in other scenarios. - Added new API for target type mappings using the new HostAccess API.
- (incompatible change) Removed default lossy string coercions. Previous behavior can be restored using the following snippets.
- Added Context.Builder#allowExperimentalOptions to control whether experimental options can be passed to a Context.
- Added Engine.Builder#allowExperimentalOptions to control whether experimental instrument and engine options can be passed.
- Removed deprecated API class
ProxyPrimitive
. - Restricting access (incompatible change) to host interop via HostAccess configurations. Use
Context.newBuilder().allowHostAccess(HostAccess.PUBLIC)
to get previous behavior. - Restricting access (incompatible change) to the host language via HostAccess configurations. Use
Context.newBuilder().allowHostAccess(HostAccess.ALL)
to get previous behavior. Configurations that useallowAllAccess(true)
are not affected by this incompatible change. - Deprecated
Context.Builder.hostClassFilter
and added the new methodContext.Builder.allowHostClassLookup
as a replacement. The name was changed change for clarity and now also allowsnull
values to indicate that no host class lookup is allowed. - Deprecated
defaultValue
ofOptionType
. Default value ofOptionKey
is sufficient. --vm.*
should now be used instead of--native.*
or--jvm.*
to pass VM options in GraalVM language launchers (the old style of option is still supported but deprecated and shows warnings on stderr).--native
and--jvm
should still be used to select the VM mode.--jvm.help
or--native.help
are deprecated in favor of--help:vm
.
- OptionCategory.DEBUG has been renamed to
OptionCategory.INTERNAL
for clarity. - Added
"static"
member to class objects that provides access to the class's static members. - OptionStability has been added for specifying the stability of an option.
- Added SourceSection.hasLines(), SourceSection.hasColumns() and SourceSection.hasCharIndex() to distinguish which positions are defined and which are not.
- Added FileSystem.getSeparator() to remove a dependency on NIO
FileSystem
for customPath
implementations. - Added support for automatic string to primitive type conversion using the Value API.
- Added FileSystem.setCurrentWorkingDirectory method to set a current working directory for relative paths resolution in the polyglot FileSystem.
- Added a Context.Builder.logHandler and Engine.Builder.logHandler methods to install a logging handler writing into a given
OutputStream
. Value.asValue(Object)
now also works if no currently entered context is available.- Primitives, host and
Proxy
values can now be shared between multiple context and engine instances. They no longer throw anIllegalArgumentException
when shared. Primitive types areBoolean
,Byte
,Short
,Integer
,Long
,Float
,Double
,Character
andString
of thejava.lang
package. Non primitive values originating from guest languages are not sharable.
- Added
MessageTransport
andMessageEndpoint
to virtualize transport of messages to a peer URI. - Added
Value.canInvokeMember()
andValue.invokeMember()
to invoke a member of an object value.
- Graal SDK was relicensed from GPLv2 with CPE to Universal Permissive License (UPL).
- Added new
ByteSequence
utility to the IO package that is intended to be used as immutable byte sequence representation. - Added support for byte based sources:
- Byte based sources may be constructed using a
ByteSequence
or from aFile
orURL
. Whether sources are interpreted as character or byte based sources depends on the specified language. Source.hasBytes()
andSource.hasCharacters()
may be used to find out whether a source is character or byte based.- Byte based sources throw an
UnsupportedOperationException
if methods that access characters, line numbers or column numbers. - Added
Source.getBytes()
to access the contents of byte based sources.
- Byte based sources may be constructed using a
- Added support for MIME types to sources:
- MIME types can now be assigned using
Source.Builder.mimeType(String)
to sources in addition to the target language. - The MIME type of a source allows languages support different kinds of input.
Language
instances allow access to the default and supported MIME types usingLanguage.getMimeTypes()
andLanguage.getDefaultMimeType()
.- MIME types are automatically detected if the source is constructed from a
File
orURL
if it is not specified explicitly. - Deprecated
Source.getInputStream()
. UseSource.getCharacters()
orSource.getBytes()
instead.
- MIME types can now be assigned using
- Context methods now consistently throw
IllegalArgumentException
instead ofIllegalStateException
for unsupported sources or missing / inaccessible languages. - Added
Engine.findHome()
to find the GraalVM home folder.
PolyglotException.getGuestObject()
now returnsnull
to indicate that no exception object is available instead of returning aValue
instance that returnstrue
forisNull()
.- Added new execution listener API that allows for simple, efficient and fine grained introspection of executed code.
- Added support for logging in Truffle languages and instruments.
- Added
Value.asValue(Object)
to convert a Java object into its value representation using the currently entered context. - Added
Context.getCurrent()
to lookup the current context to allow Java methods called by a Graal guest language to evaluate additional code in the current context. - Removed deprecated
Context.exportSymbol
andContext.importSymbol
. - Removed deprecated
Source.getCode
. - The code cache for sources is now weak. Code can be garbage collected if a source is no longer referenced but the Context or Engine is still active.
- Added
Source.Builder.cached(boolean)
to configure caching behavior by source.
- Added Context.Builder#allowHostClassLoading to allow loading of new classes by the guest language.
- Added
Value.getSourceLocation()
to find a functionSourceSection
.
- Expose Runtime name as Engine#getImplementationName();
- Deprecate Context#exportSymbol, Context#importSymbol, Context#lookup use Context#getBindings, Context#getPolyglotBindings instead.
- Remove deprecated API Engine#getLanguage, Engine#getInstrument.
- Remove deprecated Language#isHost.
- Deprecate ProxyPrimitive without replacement.
- Added Context.Builder#allAccess that allows to declare that a context has all access by default, also for new access rights.
- Added Value#as(Class) and Value.as(TypeLiteral) to convert to Java types.
- Added Context#asValue(Object) to convert Java values back to the polyglot Value representation.
- Added Value#isProxyObject() and Value#asProxyObject().
- Introduced Context.enter() and Context.leave() that allows explicitly entering and leaving the context to improve performance of performing many simple operations.
- Introduced Value.executeVoid to allow execution of functions more efficiently if not return value is expected.
- Initial revision of the polyglot API introduced.
- Initial revision of the native image API introduced.
- Initial revision of the options API introduced.