Package com.oracle.truffle.api.bytecode

Annotation Interface GenerateBytecode

@Retention(SOURCE) @Target(TYPE) public @interface GenerateBytecode
Generates a bytecode interpreter using the Bytecode DSL. The Bytecode DSL automatically produces an optimizing bytecode interpreter from a set of Node-like "operations". The following is an example of a Bytecode DSL interpreter with a single Add operation. 
 @GenerateBytecode(languageClass = MyLanguage.class)
 public abstract class MyBytecodeRootNode extends RootNode implements BytecodeRootNode {
     @Operation
     public static final class Add {
         @Specialization
         public static int doInts(int lhs, int rhs) {
             return lhs + rhs;
         }

         @Specialization
         @TruffleBoundary
         public static String doStrings(String lhs, String rhs) {
             return lhs + rhs;
         }
     }
 }

The Bytecode DSL generates a node suffixed with Gen (e.g., MyBytecodeRootNodeGen) that contains (among other things) a full bytecode encoding, an optimizing interpreter, and a Builder class to generate and validate bytecode automatically.

A node can opt in to additional features, like an uncached interpreter, boxing elimination, quickened instructions, and more. The fields of this annotation control which features are included in the generated interpreter.

For information about using the Bytecode DSL, please consult the tutorial.

Since:
24.2

  • Element Details

    • languageClass

      Class<? extends TruffleLanguage<?>> languageClass
      The TruffleLanguage class associated with this node.
      Since:
      24.2

    • enableUncachedInterpreter

      boolean enableUncachedInterpreter
      Whether to generate an uncached interpreter.

      The uncached interpreter improves start-up performance by executing uncached nodes instead of allocating and executing cached (specializing) nodes.

      The node will transition to a specializing interpreter after enough invocations/back-edges (as determined by the uncached interpreter threshold).

      Since:
      24.2
      Default:
      false

    • enableSerialization

      boolean enableSerialization
      Whether the generated interpreter should support serialization and deserialization.

      When serialization is enabled, the Bytecode DSL generates code to convert bytecode nodes to and from a serialized byte array representation. The code effectively serializes the node's execution data (bytecode, constants, etc.) and all of its non-transient fields.

      The serialization logic is defined in static serialize and deserialize methods on the generated root class. The generated BytecodeRootNodes class also overrides BytecodeRootNodes.serialize(java.io.DataOutput, com.oracle.truffle.api.bytecode.serialization.BytecodeSerializer).

      This feature can be used to avoid the overhead of parsing source code on start up. Note that serialization still incurs some overhead, as it does not trivially copy bytecode directly: in order to validate the bytecode (balanced stack pointers, valid branches, etc.), serialization encodes builder method calls and deserialization replays those calls.

      Note that the generated deserialize method takes a Supplier rather than a DataInput directly. The supplier should produce a fresh DataInput each time because the input may be processed multiple times (due to reparsing).

      Since:
      24.2
      See Also:
      Default:
      false

    • enableTagInstrumentation

      boolean enableTagInstrumentation
      Whether the generated interpreter should support Truffle tag instrumentation. When instrumentation is enabled, the generated builder will define startTag(...) and endTag(...) methods that can be used to annotate the bytecode with tags. Truffle tag instrumentation also allows you to specify implicit tagging using Operation.tags(). If tag instrumentation is enabled all tagged operations will automatically handle and insert probes from the Truffle instrumentation framework.

      Only tags that are provided by the specified Truffle language can be used.

      Since:
      24.2
      See Also:
      Default:
      false

    • enableRootTagging

      boolean enableRootTagging
      Enables automatic root tagging if instrumentation is enabled. Automatic root tagging automatically tags each root with StandardTags.RootTag and StandardTags.RootBodyTag if the language provides it.

      Root tagging requires the probe to be notified before the prolog is executed. Implementing this behavior manually is not trivial and not recommended. It is recommended to use automatic root tagging. For inlining performed by the parser it may be useful to emit custom root tag using the builder methods for inlined methods. This ensures that tools can still work correctly for inlined calls.

      Since:
      24.2
      See Also:
      Default:
      true

    • enableRootBodyTagging

      boolean enableRootBodyTagging
      Enables automatic root body tagging if instrumentation is enabled. Automatic root body tagging automatically tags each root with StandardTags.RootBodyTag if the language provides it.
      Since:
      24.2
      See Also:
      Default:
      true

    • tagTreeNodeLibrary

      Class<?> tagTreeNodeLibrary
      Allows to customize the NodeLibrary implementation that is used for tag instrumentation. This option only makes sense if enableTagInstrumentation() is set to true.

      Common use-cases when implementing a custom tag tree node library is required:

      • Allowing instruments to access the current receiver or function object
      • Implementing custom scopes for local variables instead of the default scope.
      • Hiding certain local local variables or arguments from instruments.

      Minimal example tag node library: 

       @ExportLibrary(value = NodeLibrary.class, receiverType = TagTreeNode.class)
 final class MyTagTreeNodeExports {

     @ExportMessage
     static boolean hasScope(TagTreeNode node, Frame frame) {
         return true;
     }

     @ExportMessage
     @SuppressWarnings("unused")
     static Object getScope(TagTreeNode node, Frame frame, boolean nodeEnter) throws UnsupportedMessageException {
         return new MyScope(node, frame);
     }
 }
      See the NodeLibrary javadoc for more details.
      Since:
      24.2
      See Also:
      Default:
      com.oracle.truffle.api.bytecode.TagTreeNodeExports.class

    • allowUnsafe

      boolean allowUnsafe
      Whether to use unsafe array accesses.

      Unsafe accesses are faster, but they do not perform array bounds checks. This means it is possible (though unlikely) for unsafe accesses to cause undefined behaviour. Undefined behavior may only happen due to a bug in the Bytecode DSL implementation and not language implementation code.

      Since:
      24.2
      Default:
      true

    • enableYield

      boolean enableYield
      Whether the generated interpreter should support coroutines via a yield operation.

      The yield operation returns a ContinuationResult from the current point in execution. The ContinuationResult saves the current state of the interpreter so that it can be resumed at a later time. The yield and resume actions pass values, enabling communication between the caller and callee.

      Technical note: in theoretical terms, a ContinuationResult implements an asymmetric stack-less coroutine.

      Since:
      24.2
      See Also:
      Default:
      false

    • enableBlockScoping

      boolean enableBlockScoping
      Enables block scoping, which limits a local's lifetime to the lifetime of the enclosing Block/Root operation. Block scoping is enabled by default. If this flag is set to false, locals use root scoping, which keeps locals alive for the lifetime of the root node (i.e., the entire invocation).

      The value of this flag significantly changes the behaviour of local variables, so the value of this flag should be decided relatively early in the development of a language.

      When block scoping is enabled, all local variables are scoped to the closest enclosing Block/Root operation. When a local variable's enclosing Block ends, it falls out of scope and its value is automatically cleared (or reset to a default value, if provided). Locals scoped to the Root operation are not cleared on exit. Block scoping allows the interpreter to reuse a frame index for multiple locals that have disjoint lifetimes, which can reduce the frame size.

      With block scoping, a different set of locals can be live at different bytecode indices. The interpreter retains extra metadata to track the lifetimes of each local. The local accessor methods on BytecodeNode (e.g., BytecodeNode.getLocalValues(int, Frame)) take the current bytecode index as a parameter so that they can correctly compute the locals in scope. These liveness computations can require extra computation, so accessing locals using bytecode instructions or LocalAccessors (which validate liveness at parse time) is encouraged when possible. The bytecode index should be a partial evaluation constant for performance reasons. The lifetime of local variables can also be accessed through introspection using LocalVariable.getStartIndex() and LocalVariable.getEndIndex().

      When root scoping is enabled, all local variables are assigned a unique index in the frame regardless of the current source location. They are never cleared, and frame indexes are not reused. Consequently, the bytecode index parameter on the local accessor methods on BytecodeNode has no effect. Root scoping does not retain additional liveness metadata (which may be a useful footprint optimization); this also means LocalVariable.getStartIndex() and LocalVariable.getEndIndex() methods do not return lifetime data.

      Root scoping is primarily intended for cases where the implemented language does not use block scoping. It can also be useful if the default block scoping is not flexible enough and custom scoping rules are needed.

      Since:
      24.2
      Default:
      true

    • enableQuickening

      boolean enableQuickening
      Whether to generate quickened bytecodes for user-provided operations.

      Quickened versions of instructions support a subset of the specializations defined by an operation. They can improve interpreted performance by reducing footprint and requiring fewer guards.

      Quickened versions of operations can be specified using ForceQuickening. When an instruction re-specializes itself, the interpreter attempts to automatically replace it with a quickened instruction.

      Since:
      24.2
      Default:
      true

    • storeBytecodeIndexInFrame

      boolean storeBytecodeIndexInFrame
      Whether the generated interpreter should store the bytecode index (bci) in the frame.

      By default, methods that compute location-dependent information (like BytecodeNode.getBytecodeLocation(com.oracle.truffle.api.frame.Frame, Node)) must follow Node parent pointers and scan the bytecode to compute the current bci, which is not suitable for the fast path. When this feature is enabled, an implementation can use BytecodeNode.getBytecodeIndex(com.oracle.truffle.api.frame.Frame) to obtain the bci efficiently on the fast path and use it for location-dependent computations (e.g., BytecodeNode.getBytecodeLocation(int)).

      Note that operations always have fast-path access to the bci using a bind parameter (e.g., @Bind("$bytecodeIndex") int bci); this feature should only be enabled for fast-path bci access outside of the current operation (e.g., for closures or frame introspection). Storing the bci in the frame increases frame size and requires additional frame writes, so it can negatively affect performance.

      When the bytecode index is stored in the frame, the interpreter includes extra Java assertions to validate materialized local accesses. Each access dynamically checks whether the local is in scope at the current bytecode index in the local's frame, throwing an exception if it is out of scope. Thus, enabling this flag (and Java assertions) may be helpful for debugging issues with materialized local accesses.

      Since:
      24.2
      Default:
      false

    • boxingEliminationTypes

      Class<?>[] boxingEliminationTypes
      Primitive types the interpreter should attempt to avoid boxing up. Each type should be primitive class literal (e.g., int.class).

      If boxing elimination types are provided, the cached interpreter will generate instruction variants that load/store primitive values when possible. It will automatically use these instructions in a best-effort manner (falling back on boxed representations when necessary).

      Since:
      24.2
      Default:
      {}

    • enableSpecializationIntrospection

      boolean enableSpecializationIntrospection
      Whether to generate introspection data for specializations. The data is accessible using Instruction.Argument.getSpecializationInfo().
      Since:
      24.2
      Default:
      false

    • defaultLocalValue

      String defaultLocalValue
      Sets the default value that locals return when they are read without ever being written. By default locals that were never stored throw a FrameSlotTypeException internal error when they are read, unless a default local value is specified.

      It is recommended for the default local value expression to refer to a static and final constant in the bytecode root node. For example: 

       @GenerateBytecode(..., defaultLocalValue = "DEFAULT_VALUE")
 abstract class MyBytecodeRootNode extends RootNode implements BytecodeRootNode {

     static final DefaultValue DEFAULT_VALUE = DefaultValue.INSTANCE;

     // ...
 }
      Other expressions like null or a static method call are also possible. Note that instance methods of the root node cannot be bound with the default local value expression for efficiency reasons.
      Since:
      24.2
      Default:
      ""