Package com.oracle.truffle.sl

Class SLLanguage

java.lang.Object
com.oracle.truffle.api.TruffleLanguage<SLContext>
com.oracle.truffle.sl.SLLanguage
public final class SLLanguage extends com.oracle.truffle.api.TruffleLanguage<SLContext>
SL is a simple language to demonstrate and showcase features of Truffle. The implementation is as simple and clean as possible in order to help understanding the ideas and concepts of Truffle. The language has first class functions, and objects are key-value stores.

SL is dynamically typed, i.e., there are no type names specified by the programmer. SL is strongly typed, i.e., there is no automatic conversion between types. If an operation is not available for the types encountered at run time, a type error is reported and execution is stopped. For example, 4 - "2" results in a type error because subtraction is only defined for numbers.

Types:

  • Number: arbitrary precision integer numbers. The implementation uses the Java primitive type long to represent numbers that fit into the 64 bit range, and SLBigInteger for numbers that exceed the range. Using a primitive type such as long is crucial for performance.
  • Boolean: implemented as the Java primitive type boolean.
  • String: implemented as the Java standard type String.
  • Function: implementation type SLFunction.
  • Object: efficient implementation using the object model provided by Truffle. The implementation type of objects is a subclass of DynamicObject.
  • Null (with only one value null): implemented as the singleton SLNull.SINGLETON.
The class SLTypes lists these types for the Truffle DSL, i.e., for type-specialized operations that are specified using Truffle DSL annotations.

Language concepts:

Syntax and parsing:
The syntax is described by an ANTLR 4 grammar. The parser and lexer are automatically generated by ANTLR 4. SL converts the AST to a Truffle interpreter using an AST visitor. All functions found in SL source are added to the SLFunctionRegistry, which is accessible from the SLContext.

AST vs. Bytecode interpreter:
SL has an AST interpreter and a bytecode interpreter. The interpreter used depends on the UseBytecode flag (by default, the AST interpreter is used).

Builtin functions:
Library functions that are available to every SL source without prior definition are called builtin functions. They are added to the SLFunctionRegistry when the SLContext is created. Some of the current builtin functions are

  • readln: Read a String from the standard input.
  • println: Write a value to the standard output.
  • nanoTime: Returns the value of a high-resolution time, in nanoseconds.
  • defineFunction: Parses the functions provided as a String argument and adds them to the function registry. Functions that are already defined are replaced with the new version.
  • stckTrace: Print all function activations with all local variables.

  • Nested Class Summary

    Nested classes/interfaces inherited from class com.oracle.truffle.api.TruffleLanguage

    com.oracle.truffle.api.TruffleLanguage.ContextLocalFactory<C,T>, com.oracle.truffle.api.TruffleLanguage.ContextLocalProvider<C>, com.oracle.truffle.api.TruffleLanguage.ContextPolicy, com.oracle.truffle.api.TruffleLanguage.ContextReference<C>, com.oracle.truffle.api.TruffleLanguage.ContextThreadLocalFactory<C,T>, com.oracle.truffle.api.TruffleLanguage.Env, com.oracle.truffle.api.TruffleLanguage.ExitMode, com.oracle.truffle.api.TruffleLanguage.InlineParsingRequest, com.oracle.truffle.api.TruffleLanguage.LanguageReference<L extends com.oracle.truffle.api.TruffleLanguage>, com.oracle.truffle.api.TruffleLanguage.ParsingRequest, com.oracle.truffle.api.TruffleLanguage.Provider, com.oracle.truffle.api.TruffleLanguage.Registration

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static int
    counter
     
    static final org.graalvm.options.OptionKey<com.oracle.truffle.api.bytecode.BytecodeTier>
    ForceBytecodeTier
     
    static final String
    ID
     
    static final String
    MIME_TYPE
     
    static final com.oracle.truffle.api.strings.TruffleString.Encoding
    STRING_ENCODING
     
    static final org.graalvm.options.OptionKey<Boolean>
    UseBytecode
     

    Fields inherited from class com.oracle.truffle.api.TruffleLanguage

    locals

  • Constructor Summary

    Constructors
    Constructor
    Description
    SLLanguage()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected boolean
    areOptionsCompatible(org.graalvm.options.OptionValues firstOptions, org.graalvm.options.OptionValues newOptions)
     
    protected SLContext
    createContext(com.oracle.truffle.api.TruffleLanguage.Env env)
     
    SLObject
    createObject(com.oracle.truffle.api.instrumentation.AllocationReporter reporter)
    Allocate an empty object.
    protected void
    exitContext(SLContext context, com.oracle.truffle.api.TruffleLanguage.ExitMode exitMode, int exitCode)
     
    static SLLanguage
    get(com.oracle.truffle.api.nodes.Node node)
     
    com.oracle.truffle.api.bytecode.BytecodeTier
    getForceBytecodeTier()
     
    protected Object
    getLanguageView(SLContext context, Object value)
     
    protected org.graalvm.options.OptionDescriptors
    getOptionDescriptors()
     
    com.oracle.truffle.api.RootCallTarget
    getOrCreateUndefinedFunction(com.oracle.truffle.api.strings.TruffleString name)
     
    com.oracle.truffle.api.object.Shape
    getRootShape()
     
    protected Object
    getScope(SLContext context)
     
    protected void
    initializeMultipleContexts()
    SLLanguage specifies the TruffleLanguage.ContextPolicy.SHARED in TruffleLanguage.Registration.contextPolicy().
    static void
    installBuiltin(com.oracle.truffle.api.dsl.NodeFactory<? extends SLBuiltinNode> builtin)
     
    boolean
    isSingleContext()
     
    boolean
    isUseBytecode()
     
    protected boolean
    isVisible(SLContext context, Object value)
     
    com.oracle.truffle.api.RootCallTarget
    lookupBuiltin(com.oracle.truffle.api.dsl.NodeFactory<? extends SLBuiltinNode> factory)
     
    static com.oracle.truffle.api.nodes.NodeInfo
    lookupNodeInfo(Class<?> clazz)
     
    protected com.oracle.truffle.api.CallTarget
    parse(com.oracle.truffle.api.TruffleLanguage.ParsingRequest request)
     
    protected boolean
    patchContext(SLContext context, com.oracle.truffle.api.TruffleLanguage.Env newEnv)
     
    static void
    printInstrumentationTree(PrintStream w, String indent, com.oracle.truffle.api.nodes.Node node)
     

    Methods inherited from class com.oracle.truffle.api.TruffleLanguage

    createContextLocal, createContextThreadLocal, disposeContext, disposeThread, finalizeContext, finalizeThread, getAsynchronousStackDepth, getCurrentContext, getCurrentLanguage, getLanguageHome, initializeContext, initializeMultiThreading, initializeThread, isThreadAccessAllowed, parse

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • counter

      public static volatile int counter

    • ID

      public static final String ID
      See Also:

    • MIME_TYPE

      public static final String MIME_TYPE
      See Also:

    • STRING_ENCODING

      public static final com.oracle.truffle.api.strings.TruffleString.Encoding STRING_ENCODING

    • UseBytecode

      public static final org.graalvm.options.OptionKey<Boolean> UseBytecode

    • ForceBytecodeTier

      public static final org.graalvm.options.OptionKey<com.oracle.truffle.api.bytecode.BytecodeTier> ForceBytecodeTier

  • Constructor Details

    • SLLanguage

      public SLLanguage()

  • Method Details

    • createContext

      protected SLContext createContext(com.oracle.truffle.api.TruffleLanguage.Env env)
      Specified by:
      createContext in class com.oracle.truffle.api.TruffleLanguage<SLContext>

    • patchContext

      protected boolean patchContext(SLContext context, com.oracle.truffle.api.TruffleLanguage.Env newEnv)
      Overrides:
      patchContext in class com.oracle.truffle.api.TruffleLanguage<SLContext>

    • getOptionDescriptors

      protected org.graalvm.options.OptionDescriptors getOptionDescriptors()
      Overrides:
      getOptionDescriptors in class com.oracle.truffle.api.TruffleLanguage<SLContext>

    • isUseBytecode

      public boolean isUseBytecode()

    • getForceBytecodeTier

      public com.oracle.truffle.api.bytecode.BytecodeTier getForceBytecodeTier()

    • areOptionsCompatible

      protected boolean areOptionsCompatible(org.graalvm.options.OptionValues firstOptions, org.graalvm.options.OptionValues newOptions)
      Overrides:
      areOptionsCompatible in class com.oracle.truffle.api.TruffleLanguage<SLContext>

    • getOrCreateUndefinedFunction

      public com.oracle.truffle.api.RootCallTarget getOrCreateUndefinedFunction(com.oracle.truffle.api.strings.TruffleString name)

    • lookupBuiltin

      public com.oracle.truffle.api.RootCallTarget lookupBuiltin(com.oracle.truffle.api.dsl.NodeFactory<? extends SLBuiltinNode> factory)

    • lookupNodeInfo

      public static com.oracle.truffle.api.nodes.NodeInfo lookupNodeInfo(Class<?> clazz)

    • parse

      protected com.oracle.truffle.api.CallTarget parse(com.oracle.truffle.api.TruffleLanguage.ParsingRequest request) throws Exception
      Overrides:
      parse in class com.oracle.truffle.api.TruffleLanguage<SLContext>
      Throws:
      Exception

    • printInstrumentationTree

      public static void printInstrumentationTree(PrintStream w, String indent, com.oracle.truffle.api.nodes.Node node)

    • initializeMultipleContexts

      protected void initializeMultipleContexts()
      SLLanguage specifies the TruffleLanguage.ContextPolicy.SHARED in TruffleLanguage.Registration.contextPolicy(). This means that a single TruffleLanguage instance can be reused for multiple language contexts. Before this happens the Truffle framework notifies the language by invoking initializeMultipleContexts(). This allows the language to invalidate certain assumptions taken for the single context case. One assumption SL takes for single context case is located in SLEvalRootNode. There functions are only tried to be registered once in the single context case, but produce a boundary call in the multi context case, as function registration is expected to happen more than once. Value identity caches should be avoided and invalidated for the multiple contexts case as no value will be the same. Instead, in multi context case, a language should only use types, shapes and code to speculate. For a new language it is recommended to start with TruffleLanguage.ContextPolicy.EXCLUSIVE and as the language gets more mature switch to TruffleLanguage.ContextPolicy.SHARED.
      Overrides:
      initializeMultipleContexts in class com.oracle.truffle.api.TruffleLanguage<SLContext>

    • isSingleContext

      public boolean isSingleContext()

    • getLanguageView

      protected Object getLanguageView(SLContext context, Object value)
      Overrides:
      getLanguageView in class com.oracle.truffle.api.TruffleLanguage<SLContext>

    • isVisible

      protected boolean isVisible(SLContext context, Object value)
      Overrides:
      isVisible in class com.oracle.truffle.api.TruffleLanguage<SLContext>

    • getScope

      protected Object getScope(SLContext context)
      Overrides:
      getScope in class com.oracle.truffle.api.TruffleLanguage<SLContext>

    • getRootShape

      public com.oracle.truffle.api.object.Shape getRootShape()

    • createObject

      public SLObject createObject(com.oracle.truffle.api.instrumentation.AllocationReporter reporter)
      Allocate an empty object. All new objects initially have no properties. Properties are added when they are first stored, i.e., the store triggers a shape change of the object.

    • get

      public static SLLanguage get(com.oracle.truffle.api.nodes.Node node)

    • installBuiltin

      public static void installBuiltin(com.oracle.truffle.api.dsl.NodeFactory<? extends SLBuiltinNode> builtin)

    • exitContext

      protected void exitContext(SLContext context, com.oracle.truffle.api.TruffleLanguage.ExitMode exitMode, int exitCode)
      Overrides:
      exitContext in class com.oracle.truffle.api.TruffleLanguage<SLContext>