Skip to content

Latest commit

 

History

History
770 lines (691 loc) · 105 KB

CHANGELOG.md

File metadata and controls

770 lines (691 loc) · 105 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 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.