Skip to content

Latest commit

 

History

History
1003 lines (912 loc) · 146 KB

CHANGELOG.md

File metadata and controls

1003 lines (912 loc) · 146 KB
Raw

Truffle Changelog

This changelog summarizes major changes between Truffle versions relevant to languages implementors building upon the Truffle framework. The main focus is on APIs exported by Truffle.

Version 21.1.0

  • Added methods into Instrumenter that create bindings to be attached later on. Added EventBinding.attach() method.
  • Added TruffleContext.isCancelling() to check whether a truffle context is being cancelled.
  • Added TruffleInstrument.Env.calculateContextHeapSize(TruffleContext, long, AtomicBoolean) to calculate the heap size retained by a a context.
  • Added ContextsListener.onLanguageContextCreate, ContextsListener.onLanguageContextCreateFailed, ContextsListener.onLanguageContextInitialize, and ContextsListener.onLanguageContextInitializeFailed to allow instruments to listen to language context creation start events, language context creation failure events, language context initialization start events, and language context initialization failure events, respectively.
  • Added CompilerDirectives.isExact(Object, Class) to check whether a value is of an exact type. This method should be used instead of the value != null && value.getClass() == exactClass pattern.
  • Added Frame.clear(FrameSlot). This allows the compiler to reason about the liveness of local variables. Languages are recommended to use it when applicable.
  • Added @GenerateAOT to support preparation for AOT specializing nodes. Read the (AOT tutorial)[https://github.com/oracle/graal/blob/master/truffle/docs/AOT.md] to get started with Truffle and AOT compilation.
  • Profiles now can be disabled using Profile.disable() and reset using Profile.reset().
  • Added --engine.CompileAOTOnCreate option to trigger AOT compilation on call target create.
  • Added new messages to InteropLibrary for interacting with buffer-like objects:
    • Added hasBufferElements(Object) that returns true if this object supports buffer messages.
    • Added isBufferWritable(Object) that returns true if this object supports writing buffer elements.
    • Added getBufferSize(Object) to return the size of this buffer.
    • Added readBufferByte(Object, long), readBufferShort(Object, ByteOrder, long), readBufferInt(Object, ByteOrder, long), readBufferLong(Object, ByteOrder, long), readBufferFloat(Object, ByteOrder, long) and readBufferDouble(Object, ByteOrder, long) to read a primitive from this buffer at the given index.
    • Added writeBufferByte(Object, long, byte), writeBufferShort(Object, ByteOrder, long, short), writeBufferInt(Object, ByteOrder, long, int), writeBufferLong(Object, ByteOrder, long, long), writeBufferFloat(Object, ByteOrder, long, float) and writeBufferDouble(Object, ByteOrder, long, double) to write a primitive in this buffer at the given index (supported only if isBufferWritable(Object) returns true).
  • Added Shape.getLayoutClass() as a replacement for Shape.getLayout().getType(). Returns the DynamicObject subclass provided to Shape.Builder.layout.
  • Changed the default value of --engine.MultiTier from false to true. This should significantly improve the warmup time of Truffle interpreters.

Version 21.0.0

  • If an AbstractTruffleException is thrown from the ContextLocalFactory, ContextThreadLocalFactory or event listener, which is called during the context enter, the excepion interop messages are executed without a context being entered. The event listeners called during the context enter are:
    • ThreadsActivationListener.onEnterThread(TruffleContext)
    • ThreadsListener.onThreadInitialized(TruffleContext, Thread)
    • TruffleInstrument.onCreate(Env)
    • TruffleLanguage.isThreadAccessAllowed(Thread, boolean)
    • TruffleLanguage.initializeMultiThreading(Object)
    • TruffleLanguage.initializeThread(Object, Thread)
  • Added HostCompilerDirectives for directives that guide the host compilations of Truffle interpreters.
    • HostCompilerDirectives.BytecodeInterpreterSwitch - to denote methods that contain the instruction-dispatch switch in bytecode interpreters
    • HostCompilerDirectives.BytecodeInterpreterSwitchBoundary - to denote methods that do not need to be inlined into the bytecode interpreter switch
  • Truffle DSL generated nodes are no longer limited to 64 state bits. Use these state bits responsibly.
  • 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[])).

Version 20.3.0

  • Added RepeatingNode.initialLoopStatus and RepeatingNode.shouldContinue to allow defining a custom loop continuation condition.
  • Added new specialization utility to print detailed statistics about specialization instances and execution count. See Specialization Statistics Tutorial for details on how to use it.
  • Added new specialization compilation mode that ignores "fast path" specializations and generates calls only to "slow path" specializations. This mode is intended for testing purposes to increase tests coverage. See Specialization testing documentation for more details.
  • Added TruffleFile.readSymbolicLink method to read the symbolic link target.
  • Added ReportPolymorphism.Megamorphic annotation for expressing the "report only megamorphic specializations" use case when reporting polymorphism.
  • Added new flags to inspect expansion during partial evaluation: --engine.TraceMethodExpansion=truffleTier, --engine.TraceNodeExpansion=truffleTier, --engine.MethodExpansionStatistics=truffleTier and --engine.NodeExpansionStatistics=truffleTier. Language implementations are encouraged to run with these flags enabled and investigate their output for unexpected results. See Optimizing.md for details.
  • Enabled by default the elastic allocation of Truffle compiler threads depending on the number of available processors, in both JVM and native modes. The old behavior, 1 or 2 compiler threads, can be explicitly enabled with --engine.CompilerThreads=0.
  • Added ThreadsActivationListener to listen to thread enter and leave events in instruments.
  • Added TruffleInstrument.Env.getOptions(TruffleContext) to retrieve context specific options for an instrument and TruffleInstrument.getContextOptions() to describe them. This is useful if an instrument wants to be configured per context.
  • Added TruffleContext.isClosed() to check whether a truffle context is already closed. This is useful for instruments.
  • Added TruffleContext.closeCancelled and TruffleContext.closeResourceExhausted to allow instruments and language that create inner contexts to cancel the execution of a context.
  • Added TruffleContext.isActive in addition to TruffleContext.isEntered and improved their documentation to indicate the difference.
  • Added ContextsListener.onContextResetLimit to allow instruments to listen to context limit reset events from the polyglot API.
  • All instances of TruffleContext accessible from instruments can now be closed by the instrument. Previously this was only possible for creators of the TruffleContext instance.
  • Added the ability to create context and context thread locals in languages and instruments. See ContextLocal and ContextThreadLocal for details.
  • Removed the hard "maximum node count" splitting limit controlled by TruffleSplittingMaxNumberOfSplitNodes as well as the option itself.
  • Removed polymorphism reporting from DynamicObjectLibrary. If the language wants to report polymorphism for a property access, it should do so manually using a cached specialization.
  • The iterations for LoopNode.reportLoopCount(source, iterations) must now be >= 0.
  • Added NodeLibrary, which provides guest language information associated with a particular Node location, local scope mainly and TruffleLanguage.getScope and TruffleInstrument.Env.getScope, which provides top scope object of a guest language.
  • Deprecated com.oracle.truffle.api.Scope class and methods in TruffleLanguage and TruffleInstrument.Env, which provide the scope information through that class.
  • Added scope information into InteropLibrary: InteropLibrary.isScope, InteropLibrary.hasScopeParent and InteropLibrary.getScopeParent
  • Added utility method to find an instrumentable parent node InstrumentableNode.findInstrumentableParent.
  • Deprecated DebugScope.getArguments() without replacement. This API was added without use-case.
  • Added the RootNode.isTrivial method, for specifying root nodes that are always more efficient to inline than not to.
  • Added ByteArraySupport: a helper class providing safe multi-byte primitive type accesses from byte arrays.
  • Added a new base class for Truffle exceptions, see AbstractTruffleException. The original TruffleException has been deprecated. Added new interop messages for exception handling replacing the deprecated TruffleException methods.
  • Added new messages to InteropLibrary related to exception handling:
    • Added getExceptionType(Object) that allows to specify the type of an exception, e.g. PARSE_ERROR.
    • Added isExceptionIncompleteSource(Object) allows to specify whether the parse error contained unclosed brackets.
    • Added getExceptionExitStatus(Object) allows to specify the exit status of an exception of type EXIT.
    • Added hasExceptionCause(Object) and getExceptionCause(Object) to return the cause of this error
    • Added hasExceptionStackTrace(Object) and getExceptionStackTrace(Object) to return the guest stack this of this error.
    • Added hasExceptionMessage(Object) and getExceptionMessage(Object) to provide an error message of the error.
    • Added hasExecutableName(Object) and getExecutableName(Object) to provide a method name similar to what was provided in RootNode.getName() but for executable objects.
    • Added hasDeclaringMetaObject(Object) and getDeclaringMetaObject(Object) to provide the meta object of the function.
  • Language implementations are recommended to perform the following steps to upgrade their exception implementation:
    • Convert non-internal guest language exceptions to AbstractTruffleException, internal errors should be refactored to no longer implement TruffleException.
    • Export new interop messages directly on the AbstractTruffleException subclass if necessary. Consider exporting getExceptionType(Object), getExceptionExitStatus(Object) and isExceptionIncompleteSource(Object). For other interop messages the default implementation should be sufficient for most use-cases. Consider using @ExportLibrary(delegateTo=...) to forward to a guest object stored inside of the exception.
    • Rewrite interop capable guest language try-catch nodes to the new interop pattern for handling exceptions. See InteropLibrary#isException(Object) for more information.
    • Implement the new method RootNode.translateStackTraceElement which allows guest languages to transform stack trace elements to accessible guest objects for other languages.
    • Consider making executable interop objects of the guest language implement InteropLibrary.hasExecutableName(Object) and InteropLibrary.hasDeclaringMetaObject(Object).
    • Make exception printing in the guest language use InteropLibrary.getExceptionMessage(Object), InteropLibrary.getExceptionCause(Object) and InteropLibrary.getExceptionStackTrace(Object) for foreign exceptions to print them in the style of the language.
    • Make all exports of InteropLibrary.throwException(Object) throw an instance of AbstractTruffleException. This contract will be enforced in future versions when TruffleException will be removed.
    • Attention: Since AbstractTruffleException is an abstract base class, not an interface, the exceptions the Truffle NFI throws do not extend UnsatisfiedLinkError anymore. This is an incompatible change for guest languages that relied on the exact exception class. The recommended fix is to catch AbstractTruffleException instead of UnsatisfiedLinkError.
  • Added TruffleInstrument.Env.getEnteredContext returning the entered TruffleContext.
  • Added DebuggerSession.setShowHostStackFrames and host DebugStackFrame and DebugStackTraceElement. This is useful for debugging of applications that use host interop.
  • 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.
  • Deprecated the com.oracle.truffle.api.object.dsl API without replacement. The migration path is to use DynamicObject subclasses with the com.oracle.truffle.api.object API.
  • A node parameter now needs to be provided to TruffleContext.enter() and TruffleContext.leave(Object). The overloads without node parameter are deprecated. This is useful to allow the runtime to compile the enter and leave code better if a node is passed as argument.
  • Added DebuggerSession.suspendHere to suspend immediately at the current location of the current execution thread.
  • Added RootNode.prepareForAOT that allows to initialize root nodes for compilation that were not yet executed.
  • Removed deprecation for RootNode.getLanguage(Class<?>), it is still useful to efficiently access the associated language of a root node.
  • Block node partial compilation is no longer eagerly triggered but only when the --engine.MaximumGraalNodeCount limit was reached once for a call target.
  • Lifted the restriction that the dynamic type of a DynamicObject needs to be an instance of ObjectType, allowing any non-null object. Deprecated Shape.getObjectType() that has been replaced by Shape.getDynamicType().
  • Added TruffleLanguage.Env.createHostAdapterClass to allow extending a host class and/or interfaces with a guest object via a generated host adapter class (JVM only).
  • Deprecated the old truffle-node-count based inlining heuristic and related options (namely InliningNodeBudget and LanguageAgnosticInlining).
  • Added @GenerateLibrary.pushEncapsulatingNode() that allows to configure whether encapsulating nodes are pushed or popped.

Version 20.2.0

  • Added new internal engine option ShowInternalStackFrames to show internal frames specific to the language implementation in stack traces.
  • Added new identity APIs to InteropLibrary:
    • hasIdentity(Object receiver) to find out whether an object specifies identity
    • isIdentical(Object receiver, Object other, InteropLibrary otherLib) to compare the identity of two object
    • isIdenticalOrUndefined(Object receiver, Object other) export to specify the identity of an object.
    • identityHashCode(Object receiver) useful to implement maps that depend on identity.
  • Added TriState utility class represents three states TRUE, FALSE and UNDEFINED.
  • Added InteropLibrary.getUncached() and InteropLibrary.getUncached(Object) short-cut methods for convenience.
  • Enabled by default the new inlining heuristic in which inlining budgets are based on Graal IR node counts and not Truffle Node counts.
  • Added ConditionProfile#create() as an alias of createBinaryProfile() so it can be used like @Cached ConditionProfile myProfile.
  • Improved AssumedValue utility class: Code that reads the value but can not constant fold it does not need to deopt when the value changes.
  • A TruffleFile for an empty path is no more resolved to the current working directory.
  • Added SourceBuilder.canonicalizePath(boolean) to control whether the Source#getPath() should be canonicalized.
  • Deprecated and renamed TruffleFile.getMimeType to TruffleFile.detectMimeType. The new method no longer throws IOException but returns null instead.
  • The languages are responsible for stopping and joining the stopped Threads in the TruffleLanguage.finalizeContext.
  • Added Truffle DSL @Bind annotation to common out expression for use in guards and specialization methods.
  • Added the ability to disable adoption for DSL cached expressions with type node using @Cached(value ="...", weak = true).
  • Added an option not to adopt the parameter annotated by @Cached, using @Cached(value ="...", adopt = false).
  • Added TruffleWeakReference utility to be used on partial evaluated code paths instead of the default JDK WeakReference.
  • Removed deprecated API in com.oracle.truffle.api.source.Source. The APIs were deprecated in 19.0.
  • Added CompilerDirectives.shouldNotReachHere() as a short-cut for languages to indicate that a path should not be reachable neither in compiled nor interpreted code paths.
  • All subclasses of InteropException do no longer provide a Java stack trace. They are intended to be thrown, immediately caught by the caller and not re-thrown. As a result they can now be allocated on compiled code paths and do no longer require a @TruffleBoundary or transferToInterpreterAndInvalidate() before use. Languages are encouraged to remove @TruffleBoundary annotations or leading transferToInterpreterAndInvalidate() method calls before interop exceptions are thrown.
  • All InteropException subclasses now offer a new create factory method to provide a cause. This cause should only be used if user provided guest application code caused the problem.
  • The use of InteropException.initCause is now deprecated for performance reasons. Instead pass the cause when the InteropException is constructed. The method initCause will throw UnsupportedOperationException in future versions. Please validate all calls to Throwable.initCause for language or tool implementation code.
  • Added TruffleFile.isSameFile method to test if two TruffleFiles refer to the same physical file.
  • Added new EncapsulatingNodeReference class to lookup read and write the current encapsulating node. Deprecated encapsulating node methods in NodeUtil.
  • Added support for subclassing DynamicObject so that guest languages can directly base their object class hierarchy on it, add fields, and use @ExportLibrary on subclasses. Guest language object classes should implement TruffleObject.
  • Added new DynamicObjectLibrary API for accessing and mutating properties and the shape of DynamicObject instances. This is the recommended API from now on. Other, low-level property access APIs will be deprecated and removed in a future release.

Version 20.1.0

  • Added @GenerateLibrary(dynamicDispatchEnabled = false) that allows to disable dynamic dispatch semantics for a library. The default is true.
  • Added ability to load external default exports for libraries using a service provider. See GenerateLibrary(defaultExportLookupEnabled = true).
  • The use of @NodeField is now permitted in combination with @GenerateUncached, but it throws UnsupportedOperationException when it is used.
  • It is now possible to specify a setter with @NodeField. The generated field then will be mutable.
  • Removed deprecated interoperability APIs that were deprecated in 19.0.0.
  • Removed deprecated instrumentation APIs that were deprecated in 0.33
  • The PerformanceWarningsAreFatal and TracePerformanceWarnings engine options take a comma separated list of performance warning types. Allowed warning types are call to enable virtual call warnings, instanceof to enable virtual instance of warnings and store to enables virtual store warnings. There are also all and none types to enable (disable) all performance warnings.
  • Added DebugValue#getRawValue() for raw guest language object lookup from same language.
  • Added DebugStackFrame#getRawNode() for root node lookup from same language.
  • Added DebugException#getRawException() for raw guest language exception lookup from same language.
  • Added DebugStackFrame#getRawFrame() for underlying frame lookup from same language.
  • Added TruffleInstrument.Env.getPolyglotBindings() that replaces now deprecated TruffleInstrument.Env.getExportedSymbols().
  • Added @ExportLibrary(transitionLimit="3") that allows the accepts condition of exported libraries to transition from true to false for a library created for a receiver instance. This is for example useful to export messages for array strategies.
  • Added CompilationFailureAction engine option which deprecates CompilationExceptionsArePrinted , CompilationExceptionsAreThrown, CompilationExceptionsAreFatal and PerformanceWarningsAreFatal options.
  • Added TreatPerformanceWarningsAsErrors engine option which deprecates the PerformanceWarningsAreFatal option. To replace the PerformanceWarningsAreFatal option use the TreatPerformanceWarningsAsErrors with CompilationFailureAction set to ExitVM.
  • Added bailout into performance warning kinds used by TracePerformanceWarnings, PerformanceWarningsAreFatal and CompilationExceptionsAreFatal options.
  • Added Option.deprecationMessage to set the option deprecation reason.
  • engine.Mode is now a supported option and no longer experimental.
  • Added new meta-data APIs to InteropLibrary:
    • has/getLanguage(Object receiver) to access the original language of an object.
    • has/getSourceLocation(Object receiver) to access the source location of an object (e.g. of function or classes).
    • toDisplayString(Object receiver, boolean allowsSideEffect) to produce a human readable string.
    • has/getMetaObject(Object receiver) to access the meta-object of an object.
    • isMetaObject(Object receiver) to find out whether an object is a meta-object (e.g. Java class)
    • getMetaQualifiedName(Object receiver) to get the qualified name of the meta-object
    • getMetaSimpleName(Object receiver) to get the simple name of a the meta-object
    • isMetaInstance(Object receiver, Object instance) to check whether an object is an instance of a meta-object.
  • Added TruffleLanguage.getLanguageView that allows to wrap values to add language specific information for primitive and foreign values.
  • Added TruffleLanguage.getScopedView that allows to wrap values to add scoping and visibility to language values.
  • Added TruffleInstrument.Env.getScopedView and TruffleInstrument.Env.getLanguageView to access language and scoped views from instruments.
  • Added TruffleInstrument.Env.getLanguageInfo to convert language classes to LanguageInfo.
  • Deprecated TruffleLanguage.findMetaObject, TruffleLanguage.findSourceLocation, TruffleLanguage.toString and TruffleLanguage.isObjectOfLanguage. Use the new interop APIs and language views as replacement.
  • Added support for the value conversions of DebugValue that provide the same functionality as value conversions on Value.
  • Added DebugValue#toDisplayString to convert the value to a language-specific string representation.
  • Deprecated DebugValue#as, other conversion methods should be used instead.
  • Clarify InteropLibrary javadoc documentation of message exceptions. UnsupportedMessageException is thrown when the operation is never supported for the given receiver type. In other cases UnknownIdentifierException or InvalidArrayIndexException are thrown.
  • Added TruffleLanguage.Env.initializeLanguage method to force language initialization.
  • Values of NAME properties of ReadVariableTag and WriteVariableTag extended to allow an object or an array of objects with name and source location.
  • Added support for asynchronous stack traces: TruffleLanguage.Env.getAsynchronousStackDepth(), RootNode.findAsynchronousFrames(), TruffleInstrument.Env.setAsynchronousStackDepth(), TruffleStackTrace.getAsynchronousStackTrace(), DebuggerSession.setAsynchronousStackDepth(), SuspendedEvent.getAsynchronousStacks(), DebugException.getDebugAsynchronousStacks().

Version 20.0.0

  • Add Layout#dispatch() to be able to generate override of ObjectType#dispatch() method in the generated inner *Type class.

  • Deprecated engine options engine.InvalidationReprofileCount and engine.ReplaceReprofileCount. They no longer have any effect. There is no longer reprofiling after compilation.

  • Added DebuggerSession.{suspend(), suspendAll,resume()} to allow suspending and resuming threads.

  • Add new loop explosion mode LoopExplosionKind#FULL_UNROLL_UNTIL_RETURN, which can be used to duplicate loop exits during unrolling until function returns.

  • The default LoopExplosionKind for @ExplodeLoop changed from FULL_UNROLL to FULL_UNROLL_UNTIL_RETURN, which we believe is more intuitive. We recommend reviewing your usages of @ExplodeLoop, especially those with return, break and try/catch in the loop body as those might duplicate more code than before.

  • The TruffleCheckNeverPartOfCompilation option when building a native image is now enabled by default, ensuring neverPartOfCompilation() is not reachable for runtime compilation. Use CompilerDirectives.bailout() if you want to test when a compilation fails, otherwise avoid neverPartOfCompilation() in code reachable for runtime compilation (e.g., by using @TruffleBoundary).

  • The DirectoryStream created by a relative TruffleFile passes relative TruffleFiles into the FileVisitor, even when an explicit current working directory was set.

  • Added DebuggerTester.startExecute() that allows to execute an arbitrary sequence of commands on the background thread.

  • Time specification in InteropLibrary relaxed to allow a fixed timezone when no date is present.

  • TruffleLogger.getLogger throws an IllegalArgumentException when given id is not a valid language or instrument id.

  • Node#getEncapsulatingSourceSection() is no longer a fast-path method, because getSourceSection() is not fast-path.

  • The algorithm used to generate a unique URI for a Source built without an URI was changed to SHA-256.

  • Added ExportLibrary.delegateTo attribute that allows to delegate all messages of a library to value of a final delegate field. This can be used in combination with ReflectionLibrary to improve the ability to build wrappers.

  • ReadVariableTag and WriteVariableTag added to StandardTags.

  • Truffle TCK now checks that instrumentable nodes are not used in the context of a Library.

  • Getter to check whether TruffleContext is activated or not.

  • 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 the TRUFFLE_STRICT_OPTION_DEPRECATION is set to true and the deprecated Graal option is used the Truffle runtime throws an exception listing the used deprecated options and corresponding replacements.

Version 19.3.0

  • Added ability to obtain an Internal Truffle File. The internal file is located in the language home directories and it's readable even when IO is not allowed by the Context.
  • Deprecated TruffleLanguage.Env.getTruffleFile use getInternalTruffleFile for language standard library files located in language home or getPublicTruffleFile for user files.
  • Added primitive specializations to CompilerAsserts.partialEvaluationConstant().
  • Added the new execute method to LoopNode, which allows loops to return values.
  • Added support for temporary files and directories.
  • Threads created by the embedder may now be collected by the GC before they can be disposed. If languages hold onto thread objects exposed via initializeThread they now need to do so with WeakReference to avoid leaking thread instances.
  • Support boolean literals in DSL expressions used in @Specialization and @Cached fields.
  • Added standard block node for language implementations. Using the block node allows the optimizing runtime to split big blocks into multiple compilation units. This optimization may be enabled using --engine.PartialBlockCompilation (on by default) and configured using --engine.PartialBlockCompilationSize (default 3000).
  • Added new experimental inlining heuristic in which inlining budgets are based on Graal IR node counts and not Truffle Node counts. Enable with -Dgraal.TruffleLanguageAgnosticInlining=true.
  • Deprecated DynamicObject#isEmpty(), DynamicObject#size(); use Shape#getPropertyCount() instead.
  • Deprecated Shape#getPropertyList(Pred), Shape#getKeyList(Pred), Shape#hasTransitionWithKey(Object), Shape.Allocator#locationForValue(Object, EnumSet) without replacement.
  • Added Scope.Builder#rootInstance(Object), Scope#getRootInstance() and DebugScope#getRootInstance() to provide an instance of guest language representation of the root node (e.g. a guest language function).
  • Debugger breakpoints can be restricted to a particular root instance via Breakpoint.Builder#rootInstance(DebugValue) and found later on via DebugValue#getRootInstanceBreakpoints().
  • Deprecated TruffleLanguage.getContextReference() as this method is inefficient in many situations. The most efficient context lookup can be achieved knowing the current AST in which it is used by calling Node.lookupContextReference(Class).
  • Truffle languages and instruments no longer create META-INF/truffle files, but generate service implementations for TruffleLanguage.Provider and TruffleInstrument.Provider automatically. Recompiling the TruffleLanguage using the Truffle annotation processor automatically migrates the language.
  • The Truffle DSL processor jar no longer requires the Truffle API or Graal SDK as a dependency.
  • Added interop messages for guest language exception objects: InteropLibrary#isException(Object) and InteropLibrary#throwException(Object).
  • TruffleLanguage.patchContext is invoked for all languages whose contexts were created during context pre-initialization. Originally the patchContext was invoked only for languages with initialized contexts.

Version 19.2.0

  • Added sub-process output (error output) redirection into OutputStream.
  • Added RootNode.getQualifiedName() for a better distinction when printing stack traces. Languages are encouraged to implement it, in case it differs from the root name.
  • Added methods to identify date, time, timezone, instant and duration values in InteropLibrary and TCK TypeDescriptor.
  • Added ability to read the default time zone from the language Environment with Env.getTimeZone().
  • Deprecated Env.parse and added replacement APIs Env.parseInternal and Env.parsePublic. The new API requires to differentiate between parse calls that were invoked by the guest language user and those which are part of the internal language semantics. The separation avoids accidentally exposing access to internal languages.
  • Deprecated Env.getLanguages() and added replacement APIs Env.getInternalLanguages() and Env.getPublicLanguages().
  • Added Source.newBuilder(Source) that inherits Source properties from an existing Source.
  • Added RootBodyTag.

Version 19.1.0

  • @GenerateUncached is now inherited by subclasses.
  • NodeFactory now supports getUncachedInstance that returns the uncached singleton.
  • Introduced Truffle process sandboxing. Added a TruffleLanguage.Env.newProcessBuilder method creating a new TruffleProcessBuilder to configure and start a new sub-process.
  • Added support for reading environment variables, use TruffleLanguage.Env.getEnvironment to obtain process environment variables.
  • NodeFactory now supports getUncachedInstance that returns the uncached singleton.
  • @GenerateUncached can now be used in combination with @NodeChild if execute signatures for all arguments are present.
  • Removed deprecated automatic registration of the language class as a service.
  • The LanguageProvider can override the default verfication of the TCK IdentityFunctionTest.
  • Removed deprecated and misspelled method TruffleStackTrace#getStacktrace.
  • Removed deprecated methodsTruffleStackTraceElement#getStackTrace and TruffleStackTraceElement#fillIn (use methods of TruffleStackTrace instead).
  • SlowPathException#fillInStackTrace is now final.
  • Added an ability to read a path separator used to separate filenames in a path list.
  • @TruffleBoundary methods that throw but are not annotated with @TruffleBoundary(transferToInterpreterOnException=false) will now transfer to the interpreter only once per CallTarget (compilation root).
  • Added TruffleFile.setAttribute to allow languages to set file attributes.

Version 19.0.0

  • Renamed version 1.0.0 to 19.0.0

Version 1.0.0 RC15

  • This version includes a major revision of the Truffle Interoperability APIs. Most existing APIs for Truffle Interoperability were deprecated. The compatiblity layer may cause significant performance reduction for interoperability calls.
    • Please see the Interop Migration Guide for an overview and individual @deprecated javadoc tags for guidance.
    • Deprecated classes ForeignAccess, Message, MessageResolution, Resolve and KeyInfo.
    • The following methods got deprecated:
      • InteropException.raise, with libraries there should be no need to convert checked exceptions to runtime exceptions.
      • TruffleObject.getForeignAccess().
    • Introduced new classes: InteropLibrary and InvalidArrayIndexException.
    • Added ObjectType.dispatch to configure the dynamic dispatch and deprecated ObjectType.getForeignAccessFactory.
  • Added Truffle Library API that allows language implementations to use polymorphic dispatch for receiver types with support for implementation specific caching/profiling with support for uncached dispatch.
  • Added @GenerateUncached to allow the generation of uncached Truffle DSL nodes accessible via the new static generated methodgetUncached().
    • Set the default value for @Cached to "create()". This allows @Cached to be used without attribute.
    • Added @Cached(uncached="") to specify the expression to use for the uncached node.
    • Added @Cached(allowUncached=true) to allow the cached expression to be reused as uncached expression. Only necessary if the cached expression is not trivial or there is no getUncached() static method in the node.
    • Added @Cached#parameters to allow to share the parameter specification for the cached and uncached version of a node.
    • Added getUncached() method to the following classes:
      • BranchProfile
      • ByteValueProfile
      • ConditionProfile
      • DoubleValueProfile
      • FloatValueProfile
      • IntValueProfile
      • LongValueProfile
      • LoopConditionProfile
      • PrimitiveValueProfile
      • ValueProfile
      • IndirectCallNode
  • Truffle DSL can now properly handle checked exceptions in execute methods and specializations.
  • Truffle DSL now guarantees to adopt nodes before they are executed in guards. Previously, nodes used in guards were only adopted for their second cached invocation.
  • Added @Cached.Shared to allow sharing of cached values between specialization and exported Truffle Library methods.
  • Added Node.isAdoptable() that allows Node.getParent() to always remain null even if the node is adopted by a parent. This allows to share nodes statically and avoid the memory leak for the parent reference.
  • Added NodeUtil.getCurrentEncapsulatingNode to access the current encapsulating node in nodes that are not adoptable.
  • Added the Assumption.isValidAssumption method that allows for simpler checking of assumptions in generated code.
  • Added Truffle DSL option -Dtruffle.dsl.ignoreCompilerWarnings=true|false, to ignore Truffle DSL compiler warnings. This is useful and recommended to be used for downstream testing.
  • Added @CachedContext and @CachedLanguage for convenient language and context lookup in specializations or exported methods.
  • Added Node.lookupContextReference(Class) and Node.lookupLanguageReference(Class) that allows for a more convenient lookup.
  • Deprecated RootNode.getLanguage(Class), the new language references should be used instead.
  • Added TruffleFile aware file type detector
    • Added TruffleFile.FileTypeDetector SPI to detect a file MIME type and a file encoding. A language registering FileTypeDetector has to support all the MIME types recognized by the registered detector.
    • Added TruffleFile.getMimeType method to obtain a TruffleFile MIME type.
    • Added a possibility to set an encoding in SourceBuilder
    • The Source builders are sandboxed for files and file URLs.
    • Removed usage of NIO FileTypeDetector for MIME type detection, language implementations have to migrate to TruffleFile.FileTypeDetector.
  • TruffleFile's paths from image building time are translated in image execution time into new paths using Context's FileSystem. The absolute paths pointing to files in language homes in image generation time are resolved using image execution time language homes.
  • Added Env.isPolylgotAccessAllowed() to check whether polyglot access (e.g. access to polyglot builtins) is allowed.
  • The methods Env.getPolyglotBindings() and Env.importSymbol and Env.exportSymbol now throw a SecurityException if polyglot access not allowed.
  • Added DebugValue.isNull() to check for null values, DebugValue.execute() to be able to execute values and DebugValue.asString() to get the String from String values.
  • Added the TruffleFile.getAttribute method to read a single file's attribute and [TruffleFile.getAttributes] (https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleFile.html#getAttributes-java.util.Collection-java.nio.file.LinkOption...-) method to read file's attributes as a bulk operation.

Version 1.0.0 RC14

  • Removed some deprecated elements:
    • EventBinding.getFilter
    • TruffleLanguage ParsingRequest.getFrame and ParsingRequest.getLocation
    • LoopCountReceiver
    • EventContext.parseInContext
    • NativeLibraryDescriptor.getBindings
    • Instrumenter.attachFactory and Instrumenter.attachListener
    • SuppressFBWarnings
    • TruffleBoundary.throwsControlFlowException
    • DebuggerTester.startEval
    • ExactMath.exact methods
    • TruffleInstrument.toString
    • TruffleInstrument.findMetaObject
    • TruffleInstrument.findSourceLocation
    • constructor of JSONStringBuilder
    • constructor of JSONHelper
    • constructor of CompilerDirectives
    • constructor of ExactMath
    • constructor of Truffle
    • constructor of NodeUtil
    • TruffleException.isTimeout
    • TruffleGraphBuilderPlugins.registerUnsafeLoadStorePlugins
    • TypedObject
    • Node.getLanguage
    • TVMCI.findLanguageClass
    • ExecutionContext and RootNode.getExecutionContext
    • FrameAccess.NONE
    • RootNode.setCalltarget
    • DirectCallNode.call and IndirectCallNode.call
    • FrameInstance.getFrame
    • Node.getAtomicLock
    • ExplodeLoop.merge
    • AcceptMessage
    • RootNode.reportLoopCount
    • GraalTruffleRuntime.getQueuedCallTargets
    • PrimitiveValueProfile.exactCompare
    • BranchProfile.isVisited
    • DebugStackFrame.iterator and DebugStackFrame.getValue
  • The @Option annotation can now specify the stability of an option.
  • Fixed the case of the method TruffleStackTrace.getStacktrace to TruffleStackTrace.getStackTrace.
  • Added a getter for name separator used by TruffleFile's paths.
  • Added support for receiver object in a frame's Scope: Scope.Builder receiver(String, Object), Scope.getReceiver(), Scope.getReceiverName() and DebugScope.getReceiver().
  • Added engine bound TruffleLogger for instruments. The engine bound logger can be used by threads executing without any context.

Version 1.0.0 RC13

Version 1.0.0 RC12

  • Fixed: Env.asHostException() should throw an IllegalArgumentException if the provided value is not a host exception.
  • Changed host exceptions' getExceptionObject() to return the original host exception object.

Version 1.0.0 RC11

Version 1.0.0 RC10

  • Added support for setting current working directory for TruffleFiles, see Env.setCurrentWorkingDirectory
  • Removed deprecated TruffleLanguage.Env.newSourceBuilder.
  • Added TruffleLanguage.Env.isPreInitialization method to determine whether the context is being pre-initialized.
  • Added ArrayUtils API providing additional array and/or string operations that may be intrinsified by the compiler.
  • Added a possibility to obtain a relative URI for a relative TruffleFile.
  • Added ForeignAccess.createAccess method taking a supplier of language check node, deprecated the ForeignAccess.create method with languageCheck RootNode parameter.

Version 1.0.0 RC9

  • Added support for setting the ThreadGroup and stackSize on truffle thread creation in TruffleLanguage.Env.createThread.
  • Added Instrumenter.lookupExecutionEventNode() to find an execution event node inserted at the node's location by an event binding.
  • Added SourceElement.ROOT and StepConfig.suspendAnchors() to tune debugger stepping.
  • Added KeyInfo.READ_SIDE_EFFECTS and KeyInfo.WRITE_SIDE_EFFECTS to inform about side-effects of READ/WRITE messages.
  • Added DebugValue.hasReadSideEffects() and DebugValue.hasWriteSideEffects() to test for side-effects of reading or writing the value.

Version 1.0.0 RC8

  • Added SuspendedEvent.setReturnValue to change the return value of the currently executed source location.
  • Deprecated FrameSlot#getIndex without replacement.
  • Added TruffleInstrument.Env.startServer() to get a virtual message-based server provided via MessageTransport service.
  • Added TruffleFile.relativize, TruffleFile.startsWith, TruffleFile.endsWith, TruffleFile.createLink, TruffleFile.createSymbolicLink, TruffleFile.getOwner, TruffleFile.getGroup, TruffleFile.newDirectoryStream, TruffleFile.visit, TruffleFile.copy methods.

Version 1.0.0 RC7

  • Truffle was relicensed from GPLv2 with CPE to Universal Permissive License (UPL).

  • Made all Truffle DSL annotations retention policy CLASS instead of RUNTIME. Reflecting DSL annotations at runtime is no longer possible. It is recommended to use @Introspectable instead.

  • Removed deprecated FrameDescriptor#shallowCopy (deprecated since 1.0.0 RC3).

  • Removed deprecated FrameSlot#getFrameDescriptor (deprecated since 1.0.0 RC3).

Version 1.0.0 RC6

  • Added support for byte based sources:
    • Byte based sources may be constructed using a ByteSequence or from a TruffleFile or URL. Whether sources are interpreted as character or byte based sources depends on the specified language.
    • Source.hasBytes() and Source.hasCharacters() may be used to find out whether a source is character or byte based.
    • Added Source.getBytes() to access the contents of byte based sources.
    • TruffleLanguage.Registration.mimeType is now deprecated in favor of TruffleLanguage.Registration.byteMimeTypes and TruffleLanguage.Registration.characterMimeTypes.
    • Added TruffleLanguage.Registration.defaultMimeType to define a default MIME type. This is mandatory if a language specifies more than one MIME type.
  • TruffleLanguage.Registration.id() is now mandatory for all languages and reserved language ids will now be checked by the annotation processor.
  • Deprecated Source builders and aligned them with polyglot source builders.
    • e.g. Source.newBuilder("chars").name("name").language("language").build() can be translated to Source.newBuilder("language", "chars", "name").build()
    • This is a preparation step for removing Truffle source APIs in favor of polyglot Source APIs in a future release.
  • Deprecated Source.getInputStream(). Use Source.getCharacters() or Source.getBytes() instead.
  • Deprecated TruffleLanguage.Env.newSourceBuilder(String, TruffleFile). Use Source.newBuilder(String, TruffleFile) instead.
  • Added Source.findLanguage and Source.findMimeType to resolve languages and MIME types.
  • The method Source.getMimeType() might now return null. Source builders now support null values for mimeType(String).
  • A null source name will no longer lead to an error but will be translated to Unnamed.
  • Added TruffleFile.normalize to allow explicit normalization of TruffleFile paths. TruffleFile is no longer normalized by default.
  • Added Message#EXECUTE, Message#INVOKE, Message#NEW.
  • Deprecated Message#createExecute(int), Message#createInvoke(int), Message#createNew(int) as the arity argument is no longer needed. Jackpot rules available (run mx jackpot --apply).
  • Removed APIs for deprecated packages: com.oracle.truffle.api.vm, com.oracle.truffle.api.metadata, com.oracle.truffle.api.interop.java
  • Removed deprecated class TruffleTCK.
  • Debugger API methods now throw DebugException on language failures.
  • Deprecated API methods that use java.beans package in AllocationReporter and Debugger. New add/remove listener methods were introduced as a replacement.
  • FrameDescriptor no longer shares a lock with a RootNode.

Version 1.0.0 RC5

  • Added TruffleLanguage.Env.isHostFunction.
  • Added Java interop support for converting executable values to legacy functional interfaces without a @FunctionalInterface annotation.
  • Added TruffleLogger.getLogger(String) to obtain the root loger of a language or instrument.
  • Introduced per language context policy. Languages are encouraged to configure the most permissive policy that they can support.
  • Added TruffleLanguage.areOptionsCompatible to allow customization of the context policy based on options.
  • Changed default context policy from SHARED to EXCLUSIVE, i.e. there is one exclusive language instance per polyglot or inner context by default. This can be configured by the language using the context policy.
  • TruffleInstrument.Env.lookup(LanguagInfo, Class) now requires to be entered in a context for the current thread.
  • Removed deprecated FindContextNode (deprecated since 0.25).
  • All languages now need to have a public zero argument constructor. Using a static singleton field is no longer supported.
  • Renamed and changed the return value of the method for TruffleLanguage.initializeMultiContext to TruffleLanguage.initializeMultipleContexts. The original method remains but is now deprecated.
  • Added SourceSectionFilter#includes
  • Deprecating FrameSlot#getKind and FrameSlot#setKind in favor of FrameDescriptor#getFrameSlotKind and FrameDescriptor#setFrameSlotKind.
  • The FrameDescriptor is now thread-safe from the moment it is first passed to a RootNode constructor.
    • The list returned by FrameDescriptor#getSlots no longer reflects future changes in the FrameDescriptor. This is an incompatible change.
    • The set returned by FrameDescriptor#getIdentifiers no longer reflects future changes in the FrameDescriptor. This is an incompatible change.
  • Added LanguageInfo#isInteractive
  • Added DebugStackFrame#getLanguage

Version 1.0.0 RC3

  • Removed deprecated ResultVerifier.getDefaultResultVerfier.
  • Deprecated com.oracle.truffle.api.frame.FrameDescriptor.shallowCopy and com.oracle.truffle.api.frame.FrameSlot.getFrameDescriptor
  • Added DebugValue#set to set primitive values to a debug value.
  • Added support for logging in Truffle languages and instruments.

Version 1.0.0 RC2

  • Added notification when multiple language contexts were created for a language instance. Allows languages to invalidate assumptions only valid with a single context. Returning true also allows to enable caching of ASTs per language and not only per context.
  • Added asBoxedGuestValue method that allows to expose host members for primitive interop values.
  • Added default value "inherit" to TruffleLanguage.Registration#version which makes the language to inherit version from Engine#getVersion.
  • Changed default value of TruffleInstrument.Registration#version from "" to "inherit" which makes the instrument to inherit version from Engine#getVersion. An instrument previously not specifying any version will newly get version from Engine.
  • Added new annotation @IncomingConverter and @OutgoingConverter to declare methods for generated wrappers that allow to convert values when they are exposed to or introduced by the instrumentation framework.
  • The documentation of FrameDescriptor#getSize clarifies that it returns the size of an array which is needed for storing all the slots in it using their FrameSlot#getIndex() as a position in the array. (The number may be bigger than the number of slots, if some slots are removed.)
  • Added an InstrumentExceptionsAreThrown engine option to propagate exceptions thrown by instruments.
  • Added Instrumenter.visitLoadedSourceSections to be notified about loaded source sections that corresponds to a filter.
  • Added DebugValue#canExecute to distinguish executable values and DebugValue#getProperty to get a property value by its name.
  • Removed deprecated TruffleLanguage.Env.lookupSymbol method.
  • All Truffle source objects are now automatically weakly internalized when created using the source builder. The source builder will now return the same instance for every source where it was previously just equal.
  • Added Source.Builder.cached(boolean) and Source.isCached() to configure caching behavior by source.
  • Removed deprecated Source.getCode() and SourceSection.getCode.

Version 1.0.0 RC1

  • As announced in 0.27 all classes in package com.oracle.truffle.api.vm are now deprecated.
    • Deprecated all classes in com.oracle.truffle.api.vm. Replacements can be found in the org.graalvm.polyglot package.
    • Deprecated all classes in com.oracle.truffle.api.interop.java. Replacements for embedders can be found in org.graalvm.polyglot. Replacements for language implementations can be found in TruffleLanguage.Env. See deprecated documentation on the individual methods for details.
    • Deprecated TruffleTCK. Use the new TCK instead.
    • Deprecated Debugger#find(PolyglotEngine)
    • Added Debugger#find(TruffleInstrument.Env) and Debugger#find(Engine)
  • Added FileSystem SPI to allow embedder to virtualize TruffleLanguage Input/Output operations.
  • Added EventContext.lookupExecutionEventNodes to lookup all execution event nodes created by the bindings at the source location.
  • Added TruffleLanguage#getLanguageHome to return the language directory in the GraalVM distribution or the location of the language Jar file.
  • Added TryBlockTag as a new standard tag to mark program locations to be considered as try blocks, that are followed by a catch.
  • Added DebugException, debugger methods that execute guest language code throws that exception and it's possible to create exception breakpoints that suspend when guest language exception occurs.
  • Added DebugStackTraceElement as a representation of exception stack trace.
  • Added Breakpoint.Kind to distinguish different breakpoint kinds.
  • Added ResultVerifier.getDefaultResultVerifier.
  • Added addToHostClassPath method that can be used to allow guest language users to add to the host class path.
  • Added new permission TruffleLanguage.Env#isNativeAccessAllowed to control access to the Truffle NFI.
  • Changed default permissions in language launchers to full access. The embedding API still defaults to restricted access.
  • Added TruffleInstrument.onFinalize that can be overridden to be notified about closing of Engine, while still having access to other instruments.
  • Deprecated TraceASTJSON option and related APIs.

Version 0.33

  • This release contains major changes to the instrumentation framework.
    • Deprecated @Instrumentable and replaced it with InstrumentableNode. Please see InstrumentableNode on how to specify instrumentable nodes in 0.32.
    • Added @GenerateWrapper for automatic wrapper generation.
    • Added a standard expression tag, that allows languages to expose expressions for tools to use.
    • Added the ability to listen to input values of instrumentable child nodes by specifying input filters.
    • Added the the ability to save and load instrumentable child input values in ExecutionEventNode subclasses.
    • Renamed Instrumenter#attachListener/Factory to Instrumenter#attachExecutionEventListener/Factory. (jackpot rule available)
    • Automatic instrumentation wrapper generation now delegates non execute abstract methods to the delegate node.
    • Added a Tag base class now required to be used by all tags.
    • Added tag identifiers to allow the lookup of language specific tags in tools without compile time dependency to the languguage.
    • Added assertions to verify that instrumentable nodes that are annotated with a standard tag return a source section if their root node returns a source section.
    • Added assertions to verify that execution events always return interop values.
    • Added the ability for instrumentable nodes to a expose a node object. This object is intended to contain language specific properties of the node.
  • Added expression-stepping into debugger APIs. To support debugging of both statements and expressions, following changes were made:
  • Added column filters on SourceSectionFilter.Builder and Breakpoint.Builder.
  • Added Instrumenter.attachExecuteSourceListener to be able to listen on source execution events.
  • Added InstrumentableNode.findNearestNodeAt to be able to find the nearest tagged node to the given source character index. This is used to auto-correct breakpoint locations.
  • Added Breakpoint.ResolveListener to listen on breakpoint location resolution. Breakpoints are now resolved after the source is to be executed for the first time and breakpoint location is adjusted to match the nearest instrumentable node.
  • Added new DSL annotation @Executed that allows to manually specify executed node fields.
  • The Truffle Node traversal order was slightly changed to always respect field declaration order (super class before sub class).
  • The Assumption interface has an additional override for the invalidate method to provide a message for debugging purposes.
  • Deprecated KeyInfo.Builder. Use bitwise constants in the KeyInfo class instead. Introduced new flag KeyInfo.INSERTABLE to indicate that a key can be inserted at a particular location, but it does not yet exist.
  • Deprecated TruffleLanguage#getLanguageGlobal, implement top scopes instead.
  • Deprecated TruffleLanguage#findExportedSymbol, use the polyglot bindings TruffleLanguage.Env for exporting symbols into the polyglot scope explicitely. The polyglot scope no longer supports implicit exports, they should be exposed using top scopes instead.
  • Remove deprecated TruffleInstrument#describeOptions and TruffleLanguage#describeOptions
  • Remove deprecated TruffleLanguage.Env#lookupSymbol without replacement.
  • Remove deprecated TruffleLanguage.Env#importSymbols, use the polyglot bindings instead.
  • Removed deprecated APIs and public debug classes in truffle.api.object and truffle.object packages, respectively.
  • Removed internal truffle.object package from javadoc.
  • Added the compiler directive castExact.
  • Added skipped exception types: IndexOutOfBoundsException, BufferOverflowException, and BufferUnderflowException.
  • Introduced support for the experimental automated monomorphization feature:
  • Added TruffleException.getSourceLocation() for syntax errors which don't have a Node.
  • Changed member lookup on Class host objects (as obtained by e.g. obj.getClass()) to expose Class instance members, while TruffleLanguage.Env.lookupHostSymbol(String) returns a companion object providing the static members of the class and serving as a constructor.

Version 0.32

Version 0.31

  • Removed deprecated com.oracle.truffle.api.source.LineLocation class.
  • Added RootNode#isCaptureFramesForTrace() to allow subclasses to configure capturing of frames in TruffleException instances and TruffleStackTraceElement#getFrame() to access the captured frames.
  • MaterializedFrame changed to extend VirtualFrame, to be able to call methods taking VirtualFrame from behind Truffle boundary.
  • Added ExecutableNode, TruffleLanguage.parse(InlineParsingRequest) and TruffleInstrument.Env.parseInline to parse an inline code snippet at the provided location and produce an AST fragment that can be executed using frames valid at the provided location. ParsingRequest.getLocation() and ParsingRequest.getFrame() methods were deprecated in favor of InlineParsingRequest, EventContext.parseInContext() was deprecated in favor of TruffleInstrument.Env.parseInline().
  • RootNode now extends ExecutableNode.
  • Removed deprecated methods TruffleLanguage.parse(Source, Node, String...) and TruffleLanguage.evalInContext(Source, Node, MaterializedFrame) and constructor RootNode(Class, SourceSection, FrameDescriptor).
  • Java Interop now wraps exceptions thrown by Java method invocations in host exceptions.
  • Added JavaInterop.isHostException and JavaInterop.asHostException to identify and unwrap host exceptions, respectively.
  • Added support for TruffleLanguage context pre-initialization in the native image. To support context pre-initialization a language has to implement the patchContext method.
  • The profiler infrastructure (CPUSampler, CPUTracer and MemoryTracer) moved to a new tools suite.
  • Added LanguageInfo.isInternal
  • Removed special Java interop support for java.util.Map.
  • Added a mechanism to unwind execution nodes in instrumentation by EventContext.createUnwind, ExecutionEventListener.onUnwind, ExecutionEventNode.onUnwind and ProbeNode.onReturnExceptionalOrUnwind. ProbeNode.UNWIND_ACTION_REENTER constant added.
  • Deprecated ProbeNode.onReturnExceptional() in favor of ProbeNode.onReturnExceptionalOrUnwind().
  • The wrapper node specification has changed, see ProbeNode. If the annotation processor is used (@Instrumentable annotation) then just a recompile is required. Manually written wrappers need to be updated.
  • Added SuspendedEvent.prepareUnwindFrame to unwind frame(s) during debugging.
  • Added DebuggerTester constructor that takes Context.Builder.
  • Removed deprecated DebuggerTester constructor that takes the legacy PolyglotEngine.Builder.
  • Removed deprecated methods in JavaInterop: isNull, isArray, isBoxed, unbox, getKeyInfo.
  • Disallowed null as FrameSlot identifier.
  • Removed deprecated FrameSlot constructor and FrameDescriptor.create methods.
  • Changed the behavior of exception handling (TruffleException) to capture stack frames lazily

Version 0.30

Version 0.29

Version 0.28

4-Oct-2017

  • Truffle languages may support access to contexts from multiple threads at the same time. By default the language supports only single-threaded access.
  • Languages now need to use the language environment to create new threads for a context. Creating Threads using the java.lang.Thread constructor is no longer allowed and will be blocked in the next release.
  • Added JavaInterop.isJavaObject(Object) method overload.
  • Deprecated helper methods in JavaInterop: isNull, isArray, isBoxed, unbox, getKeyInfo. ForeignAccess already provides equivalent methods: sendIsNull, sendIsArray, sendIsBoxed, sendUnbox, sendKeyInfo, respectively.
  • Deprecated all String based API in Source and SourceSection and replaced it with CharSequence based APIs. Automated migration with Jackpot rules is available (run mx jackpot --apply).
  • Added Source.Builder.language and Source.getLanguage to be able to set/get source langauge in addition to MIME type.
  • Added the inCompilationRoot compiler directive.
  • Deprecated TruffleBoundary#throwsControlFlowException and introduced TruffleBoundary#transferToInterpreterOnException.

Version 0.27

16-Aug-2017

Version 0.26

18-May-2017

Version 0.25

3-Apr-2017

Version 0.24

1-Mar-2017

Version 0.23

1-Feb-2017

  • Incompatible: Removed most of deprecated APIs from the com.oracle.truffle.api.source package.
  • Enabled the new flat generated code layout for Truffle DSL as default. To use it just recompile your guest language with latest Truffle annotation processor. The new layout uses a bitset to encode the states of specializations instead of using a node chain for efficiency. The number of specializations per operation is now limited to 127 (with no implicit casts used). All changes in the new layout are expected to be compatible with the old layout. The optimization strategy for implicit casts and fallback handlers changed and might produce different peak performance results.
  • Deprecated the frame argument for IndirectCallNode and DirectCallNode. The frame argument is no longer required.
  • Deprecated FrameInstance.getFrame(FrameAccess, boolean). Usages need to be replaced by FrameInstance.getFrame(FrameAccess). The slowPath parameter was removed without replacement.
  • Deprecated FrameAccess.NONE without replacement.
  • FrameInstance.getFrame now throws an AssertionError if a local variable of a frame was written in READ_ONLY frame access mode.

Version 0.22

13-Jan-2017

Version 0.21

6-Dec-2016

  • Added Source.isInteractive() to inform languages of a possibility to use polyglot engine streams during execution.
  • Unavailable SourceSections created by different calls to createUnavailableSection() are no longer equals(). This means builtins can share a single Source and call createUnavailableSection() for each builtin to be considered different in instrumentation.

Version 0.20

23-Nov-2016

  • Deprecated Node.getAtomicLock() and replaced it with Node.getLock() which returns a Lock.
  • Switching the source and target levels to 1.8
  • Significant improvements in Java/Truffle interop

Version 0.19

27-Oct-2016

  • New helper methods in JavaInterop: isArray, isBoxed, isNull, isPrimitive, unbox, asTruffleValue.
  • Relaxed the restrictions for calling methods on SuspendedEvent and DebugStackFrame from other threads than the execution thread. Please see the javadoc of the individual methods for details.

Version 0.18

1-Oct-2016

  • Added Instrumenter.querySourceSections(SourceSectionFilter) to get a filtered list of loaded instances.
  • Added SourceSectionFilter.ANY, which always matches.
  • Added Message.KEYS to let languages enumerate properties of its objects
  • Deprecated LineLocation, SourceSection.getLineLocation(), Source.createLineLocation(int) without replacement.
  • Deprecated SourceSection.getShortDescription(); users can replace uses with their own formatting code.
  • Deprecated SourceSection.createUnavailable(String, String) and replaced it with.
  • Added Source.createUnavailableSection(), SourceSection.isAvailable() to find out whether a source section is available.
  • SourceSection.createSourceSection(int,int) now only throws IllegalArgumentExceptions if indices that are out of bounds with the source only when assertions (-ea) are enabled.
  • Deprecated Source.createSection(int, int, int, int)

Version 0.17

1-Sep-2016

Removals, Deprecations and Breaking Changes

  • This release removes many deprecated APIs and is thus slightly incompatible

    • Remove deprecated instrumentation API package com.oracle.truffle.api.instrument and all its classes.
    • Remove deprecated API method TruffleLanguage.isInstrumentable(Node), TruffleLanguage.getVisualizer(), TruffleLanguage.createWrapperNode(), TruffleLanguage.Env.instrumenter(), RootNode.applyInstrumentation()
    • Remove deprecated API Debugger.setTagBreakpoint
    • Remove deprecated API RootNode.applyInstrumentation
    • Remove deprecated tagging API in SourceSection and Source.

  • PolyglotEngine eval method and few similar ones no longer declare throws IOException. The I/O now only occurs when operating with Source. The evaluation of already loaded sources doesn't need to perform any I/O operations and thus it makes little sense to require callers to handle the IOException. This change is binary compatible, yet it is source incompatible change. You may need to adjust your sources to compile.

  • Deprecate support for the "identifier" associated with each SourceSection

  • Deprecated PolyglotEngine.Builder.onEvent(EventConsumer) and class EventConsumer, debugger events are now dispatched using the DebuggerSession.

  • @Fallback does not support type specialized arguments anymore.

Additions

  • All debugging APIs are now thread-safe and can be used from other threads.

  • Changed the debugging API to a session based model.

    • Added Debugger.find(TruffleLanguage.Env) to lookup the debugger when inside a guest language implementation.
    • Added Debugger.startSession(SuspendedCallback) to start a new debugging session using a SuspendedCallback as replacement for ExecutionEvent.prepareStepInto().
    • Added class DebuggerSession which represents a debugger session where breakpoints can be installed and the execution can be suspended and resumed.
    • Added Breakpoint.newBuilder methods to create a new breakpoint using the builder pattern based on Source, URI or SourceSections.
    • Added Breakpoint.isResolved() to find out whether the source location of a breakpoint is loaded by the guest language.
    • Added Breakpoint.isDisposed() to find out whether a breakpoint is disposed.
    • Added SuspendedEvent.getReturnValue() to get return values of calls during debugging.
    • Added SuspendedEvent.getBreakpoints() to return the breakpoints that hit for a suspended event.
    • Added SuspendedEvent.getStackFrames() to return all guest language stack frames.
    • Added SuspendedEvent.getTopStackFrame() to return the topmost stack frame.
    • Added SuspendedEvent.getSourceSection() to return the current guest language execution location
    • Added SuspendedEvent.getSourceSections() to return all guest language execution locations of the current method in the AST.
    • Added class DebugStackFrame which represents a guest language stack frame. Allows to get values from the current stack frame, access stack values and evaluate inline expressions.
    • Added class DebugValue which represents a value on a stack frame or the result of an evaluated expression.
    • Added class DebuggerTester which represents a utility for testing guest language debugger support more easily.
    • Deprecated Breakpoint.getCondition() and replaced it with Breakpoint.getConditionExpression() to return a String instead of a Source object.
    • Deprecated Breakpoint.setCondition(String) and replaced it with Breakpoint.setConditionExpression(String) to avoid throwing IOException.
    • Deprecated class ExecutionEvent and replaced it with Debugger.startSession(SuspendedCallback)
    • Deprecated Debugger methods setLineBreakpoint, getBreakpoints, pause. Replacements are available in the DebuggerSession class
    • Deprecated Breakpoint.getState() to be replaced with BreakpointisResolved(), BreakpointisDisposed() and Breakpoint.isEnabled().
    • Deprecated SuspendedEvent.getNode() and SuspendedEvent.getFrame() without direct replacement.
    • Deprecated SuspendedEvent.getRecentWarnings() and replaced it with SuspendedEvent.getBreakpointConditionException(Breakpoint)
    • Deprecated SuspendedEvent.eval and replaced it with DebugStackFrame.eval(String)
    • Deprecated SuspendedEvent.getStack() and replaced it with SuspendedEvent.getStackFrames()
    • Deprecated SuspendedEvent.toString(Object, FrameInstance) and replaced it with DebugValue.as(String.class).

  • TruffleLanguage.createContext supports post initialization callback

  • Added SourceSectionFilter.Builder.sourceIs(SourcePredicate) to filter for source sections with a custom source predicate.

  • Added TruffleInstrument.Env.isEngineRoot(RootNode) to find out where the context of the current evaluation ends when looking up the guest language stack trace with TruffleRuntime.iterateFrames().

  • Added TruffleInstrument.Env.toString(Node, Object) to allow string conversions for objects given a Node to identify the guest language.

  • Added EventContext.lookupExecutionEventNode(EventBinding) to lookup other execution event nodes using the binding at a source location.

  • Added Node.getAtomicLock() to allow atomic updates that avoid creating a closure.

Version 0.16

  • Layout now accepts an alternative way to construct an object with the build method instead of create.
  • TruffleTCK tests simple operation on foreign objects. For example, a simple WRITE accesss, a HAS_SIZE access, or an IS_NULL access. It also tests the message resolution of Truffle language objects, which enables using them in other languages.

Version 0.15

1-Jul-2016

  • Source shall be constructed via its newBuilder methods. The other ways to construct or modify source objects are now deprecated.
  • RootNode.getName to provide name of a method or function it represents.
  • Instruments are now loaded eagerly - which has been reported as an observable behavioral change.
  • The Instrumenter now allows one to observe when sources and source sections are being loaded via attaching a listener.
  • Control the way loops are exploded with a new LoopExplosionKind enum.
  • SuspendedEvent provides a way to convert any value on stack to its string representation.
  • TruffleTCK checks whether languages properly support being interrupted after a time out
  • Language implementations are encouraged to mark their internal sources as internal

Version 0.14

2-Jun-2016

  • Source has been rewritten to be more immutable. Once (part of) content of a source is loaded, it cannot be changed.
  • Methods fromNamedAppendableText, fromNamedText and setFileCaching of Source has been deprecated as useless or not well defined
  • New method Source.getURI() has been introduced and should be used as a persistent identification of Source rather than existing getName() & co. methods. Debugger is using the URI to attach breakpoints to not yet loaded sources
  • Debugger introduces new halt tag to make it easier to simulate concepts like JavaScript's debugger statement
  • Debugger can be paused via the Debugger.pause method
  • @CompilationFinal annotation can now specify whether the finality applies to array elements as well
  • TruffleTCK has been enhanced to test behavior of languages with respect to foreign array objects

Version 0.13

22-Apr-2016

  • AcceptMessage has been deprecated, replaced by MessageResolution & co. annotations. Now all message-oriented annotations need to be placed in a single source file. That simplifies readability as well as improves incremental compilation in certain systems.
  • Deprecated Node.assignSourceSection removed. This reduces the amount of memory occupied by Node instance.
  • PolyglotEngine.Value.execute is now as fast as direct CallTarget.call. Using the PolyglotEngine abstraction now comes with no overhead. Just JPDA debuggers need to turn debugging on explicitly.
  • Sharing of efficient code/AST between multiple instances of PolyglotEngine is possible. Using more than one PolyglotEngine resulted in code de-opt previously. That isn't the case anymore. Future version of the API will provide explicit control over the set of engines that share the code.
  • Simple language JAR no longer contains test classes. There is a separate simple language tests distribution.

Version 0.12

  • The Instrumentation Framework has been revised and has new APIs that are integrated into the PolyglotEngine.
  • Instrumentation support required of language implementations is specified as abstract methods on TruffleLanguage.
  • Clients access instrumentation services via an instance of Instrumenter, provided by the Polyglot framework.
  • TruffleRuntime#iterateFrames now starts at the current frame.

Version 0.11

28-Jan-2016

  • Improved interop API
  • PolyglotEngine.Builder.getConfig
  • TruffleLanguage.Env.isMimeTypeSupported

Version 0.10

18-Dec-2015

  • Profile API classes moved into its own com.oracle.truffle.api.profiles package

Version 0.9

21-Oct-2015

  • Debugger API

Version 0.8

17-Jul-2015, Repository Revision

  • The Truffle repository no longer contains Graal
  • PolyglotEngine is an entry point for creating, building and running multi language Truffle systems
  • Implement TruffleLanguage and use @Registration to register your language into the Truffle polyglot system
  • Include Truffle TCK (test compatibility kit) into your test cases to verify your language implementation is compliant enough
  • Interoperability API polished
  • Cleanup of Source related API

Version 0.7

29-Apr-2015, Repository Revision

  • New, faster partial evaluation (no more TruffleCache).
  • If a method is annotated with @ExplodeLoop and contains a loop that can not be exploded, partial evaluation will fail.
  • Truffle background compilation is now multi-threaded.
  • Experimental merge=true flag for @ExplodeLoop allows building bytecode-based interpreters (see BytecodeInterpreterPartialEvaluationTest).
  • Added Node#deepCopy as primary method to copy ASTs.
  • Disable inlining across Truffle boundary by default. New option TruffleInlineAcrossTruffleBoundary default false.
  • Node.replace(Node) now guards against non-assignable replacement, and Node.isReplacementSafe(Node) checks in advance.
  • Instrumentation: AST "probing" is now safe and implemented by Node.probe(); language implementors need only implement Node.isInstrumentable() and Node.createWrapperNode().
  • Instrumentation: A new framework defines a category of simple "instrumentation tools" that can be created, configured, and installed, after which they autonomously collect execution data of some kind.
  • Instrumentation: A new example "instrumentation tool" is a language-agnostic collector of code coverage information (CoverageTracker); there are two other examples.
  • Removed unsafe compiler directives; use sun.misc.Unsafe instead.
  • Removed Node#onAdopt().
  • Implemented a new generated code layout that reduces the code size.
  • Changed all methods enclosed in a @TypeSystem must now be static.
  • Changed all methods enclosed in generated type system classes are now static.
  • Deprecated the type system constant used in the generated type system classes.
  • Changed NodeFactory implementations are no longer generated by default. Use {Node}Gen#create instead of {Node}Factory#create to create new instances of nodes.
  • Added @GenerateNodeFactory to generate NodeFactory implementations for this node and its subclasses.
  • Deprecated @NodeAssumptions for removal in the next release.
  • Deprecated experimental @Implies for removal in the next release.
  • Added new package c.o.t.api.dsl.examples to the c.o.t.api.dsl project containing documented and debug-able Truffle-DSL use cases.
  • Changed "typed execute methods" are no longer required for use as specialization return type or parameter. It is now sufficient to declare them in the @TypeSystem.
  • Added @Cached annotation to express specialization local state.
  • Added Specialization#limit to declare a limit expression for the maximum number of specialization instantiations.
  • Changed syntax and semantics of Specialization#assumptions and Specialization#guards. They now use a Java like expression syntax.
  • Changed guard expressions that do not bind any dynamic parameter are invoked just once per specialization instantiation. They are now asserted to be true on the fast path.
  • Renamed @ImportGuards to @ImportStatic.
  • Changed declaring a @TypeSystemReference for a node that contains specializations is not mandatory anymore.
  • Changed types used in specializations are not restricted on types declared in the type system anymore.
  • Changed nodes that declare all execute methods with the same number of evaluated arguments as specialization arguments do not require @NodeChild annotations anymore.
  • Changed types used in checks and casts are not mandatory to be declared in the type system.

Version 0.6

19-Dec-2014, Repository Revision

  • Instrumentation: add Instrumentable API for language implementors, with most details automated (see package com.oracle.truffle.api.instrument).
  • The BranchProfile constructor is now private. Use BranchProfile#create() instead.
  • Renamed @CompilerDirectives.SlowPath to @CompilerDirectives.TruffleBoundary
  • Renamed RootNode#isSplittable to RootNode#isCloningAllowed
  • Removed RootNode#split. Cloning ASTs for splitting is now an implementation detail of the Truffle runtime implementation.
  • Renamed DirectCallNode#isSplittable to DirectCallNode#isCallTargetCloningAllowed
  • Renamed DirectCallNode#split to DirectCallNode#cloneCallTarget
  • Renamed DirectCallNode#isSplit to DirectCallNode#isCallTargetCloned
  • Added PrimitiveValueProfile.
  • Added -G:TruffleTimeThreshold=5000 option to defer compilation for call targets
  • Added RootNode#getExecutionContext to identify nodes with languages
  • Removed FrameTypeConversion interface and changed the corresponding FrameDescriptor constructor to have a default value parameter instead.
  • Removed CompilerDirectives.unsafeFrameCast (equivalent to a (MaterializedFrame) cast).
  • Added TruffleRuntime#getCapability API method.
  • Added NodeInterface and allowed child field to be declared with interfaces that extend it.
  • Added CompilerOptions and allowed it to be set for ExecutionContext and RootNode.
  • Added experimental object API (see new project com.oracle.truffle.api.object).

Version 0.5

23-Sep-2014, Repository Revision

  • Added TruffleRuntime#getCallTargets() to get all call targets that were created and are still referenced.
  • Added NeverValidAssumption to complement AlwaysValidAssumption.
  • Fixed a bug in AssumedValue that may not invalidate correctly.
  • New option, -G:+/-TruffleCompilationExceptionsAreThrown, that will throw an OptimizationFailedException for compiler errors.

Version 0.4

19-Aug-2014, Repository Revision

Truffle

  • Change API for stack walking to a visitor: TruffleRuntime#iterateFrames replaces TruffleRuntime#getStackTrace
  • New flag -G:+TraceTruffleCompilationCallTree to print the tree of inlined calls before compilation.
  • truffle.jar: strip out build-time only dependency into a seperated JAR file (truffle-dsl-processor.jar)
  • New flag -G:+TraceTruffleCompilationAST to print the AST before compilation.
  • New experimental TypedObject interface added.
  • Added isVisited method for BranchProfile.
  • Added new ConditionProfile, BinaryConditionProfile and CountingConditionProfile utility classes to profile if conditions.

Version 0.3

9-May-2014, Repository Revision

  • The method CallTarget#call takes now a variable number of Object arguments.
  • Support for collecting stack traces and for accessing the current frame in slow paths (see TruffleRuntime#getStackTrace).
  • Renamed CallNode to DirectCallNode.
  • Renamed TruffleRuntime#createCallNode to TruffleRuntime#createDirectCallNode.
  • Added IndirectCallNode for calls with a changing CallTarget.
  • Added TruffleRuntime#createIndirectCallNode to create an IndirectCallNode.
  • DirectCallNode#inline was renamed to DirectCallNode#forceInlining().
  • Removed deprecated Node#adoptChild.

Version 0.2

25-Mar-2014, Repository Revision

  • New API TruffleRuntime#createCallNode to create call nodes and to give the runtime system control over its implementation.
  • New API RootNode#getCachedCallNodes to get a weak set of CallNodes that have registered to call the RootNode.
  • New API to split the AST of a call-site context sensitively. CallNode#split, CallNode#isSplittable, CallNode#getSplitCallTarget, CallNode#getCurrentCallTarget, RootNode#isSplittable, RootNode#split.
  • New API to inline a call-site into the call-graph. CallNode#isInlinable, CallNode#inline, CallNode#isInlined.
  • New API for the runtime environment to register CallTargets as caller to the RootNode. CallNode#registerCallTarget.
  • Improved API for counting nodes in Truffle ASTs. NodeUtil#countNodes can be used with a NodeFilter.
  • New API to declare the cost of a Node for use in runtime environment specific heuristics. See NodeCost, Node#getCost and NodeInfo#cost.
  • Changed Node#replace reason parameter type to CharSequence (to enable lazy string building)
  • New Node#insert method for inserting new nodes into the tree (formerly adoptChild)
  • New Node#adoptChildren helper method that adopts all (direct and indirect) children of a node
  • New API Node#atomic for atomic tree operations
  • Made Node#replace thread-safe

Version 0.1

5-Feb-2014, Repository Revision

  • Initial version of a multi-language framework on top of Graal.