Implement YieldOperation

Author: DSouzaM

truffle/CHANGELOG.md

@@ -10,9 +10,10 @@ This changelog summarizes major changes between Truffle versions relevant to lan
 * GR-67821: `TruffleLanguage.Env#createSystemThread` is now allowed to be be called from a system thread now without an explicitly entered context.
 * GR-67702: Specialization DSL: For nodes annotated with `@GenerateInline`, inlining warnings emitted for `@Cached` expressions are now suppressed if the inlined node is explicitly annotated with `@GenerateInline(false)`. This avoids unnecessary warnings if inlining for a node was explicitly disabled.
 * GR-66310: Added support for passing arrays of primitive types to native code through the Truffle NFI Panama backend.
-* GR-61292 Specialization DSL: Single specialization nodes no longer specialize on first execution unless they use assumptions, cached state, or multiple instances. This was done to improve the interpreter performance and memory footprint of such nodes. As a result, these nodes no longer invalidate on first execution, which means they can no longer be used as an implicit branch profile. Language implementations are encouraged to check whether they are relying on this behavior and insert explicit branch profiles instead (see `BranchProfile` or `InlinedBranchProfile`).
+* GR-61292: Specialization DSL: Single specialization nodes no longer specialize on first execution unless they use assumptions, cached state, or multiple instances. This was done to improve the interpreter performance and memory footprint of such nodes. As a result, these nodes no longer invalidate on first execution, which means they can no longer be used as an implicit branch profile. Language implementations are encouraged to check whether they are relying on this behavior and insert explicit branch profiles instead (see `BranchProfile` or `InlinedBranchProfile`).
 * GR-64005: Bytecode DSL: `@Operation` annotated classes can now inherit specializations and methods from super classes which are also declared in the same bytecode root node class. Language implementations no longer need to use operation proxies to use specialization inheritance.
 * GR-67146: Specialization DSL: Added `@Bind` support for frames (including materialized frames).
+* GR-67146: Bytecode DSL: Added support for user-defined yield operations using `@Yield`. These operations behave like the built-in yield but allow you to customize the yield result or perform custom logic on yield.
 
 ## Version 25.0
 * GR-31495 Added ability to specify language and instrument specific options using `Source.Builder.option(String, String)`. Languages may describe available source options by implementing `TruffleLanguage.getSourceOptionDescriptors()` and `TruffleInstrument.getSourceOptionDescriptors()` respectively.

truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/CustomYieldTest.java

@@ -57,13 +57,17 @@
 import com.oracle.truffle.api.bytecode.BytecodeRootNode;
 import com.oracle.truffle.api.bytecode.BytecodeRootNodes;
 import com.oracle.truffle.api.bytecode.BytecodeTier;
+import com.oracle.truffle.api.bytecode.ContinuationRootNode;
 import com.oracle.truffle.api.bytecode.GenerateBytecode;
 import com.oracle.truffle.api.bytecode.Operation;
+import com.oracle.truffle.api.bytecode.Yield;
+import com.oracle.truffle.api.dsl.Bind;
 import com.oracle.truffle.api.dsl.ImplicitCast;
 import com.oracle.truffle.api.dsl.Specialization;
 import com.oracle.truffle.api.dsl.TypeSystem;
 import com.oracle.truffle.api.dsl.TypeSystemReference;
 import com.oracle.truffle.api.frame.FrameDescriptor;
+import com.oracle.truffle.api.frame.MaterializedFrame;
 import com.oracle.truffle.api.impl.asm.ClassReader;
 import com.oracle.truffle.api.impl.asm.ClassVisitor;
 import com.oracle.truffle.api.impl.asm.MethodVisitor;
@@ -456,6 +460,15 @@ static double doDefault(double a0, double a1) {
                 return 1.0d;
             }
         }
+
+        // Though it is a custom operation, the yield should not be outlined.
+        @Yield
+        static final class MyYield {
+            @Specialization
+            static Object doDefault(Object result, @Bind ContinuationRootNode root, @Bind MaterializedFrame frame) {
+                return result;
+            }
+        }
     }
 
     @TypeSystem

truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/InstructionBytecodeSizeTest.java

@@ -242,6 +242,7 @@ meth public com.oracle.truffle.api.frame.MaterializedFrame getFrame()
 meth public java.lang.Object continueWith(java.lang.Object)
 meth public java.lang.Object getResult()
 meth public java.lang.String toString()
+meth public static com.oracle.truffle.api.bytecode.ContinuationResult create(com.oracle.truffle.api.bytecode.ContinuationRootNode,com.oracle.truffle.api.frame.MaterializedFrame,java.lang.Object)
 supr java.lang.Object
 hfds frame,result,rootNode
 
@@ -640,6 +641,14 @@ CLSS public abstract interface !annotation com.oracle.truffle.api.bytecode.Varia
 intf java.lang.annotation.Annotation
 meth public abstract !hasdefault int startOffset()
 
+CLSS public abstract interface !annotation com.oracle.truffle.api.bytecode.Yield
+ anno 0 java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy value=SOURCE)
+ anno 0 java.lang.annotation.Target(java.lang.annotation.ElementType[] value=[TYPE])
+intf java.lang.annotation.Annotation
+meth public abstract !hasdefault boolean forceCached()
+meth public abstract !hasdefault java.lang.Class<? extends com.oracle.truffle.api.instrumentation.Tag>[] tags()
+meth public abstract !hasdefault java.lang.String javadoc()
+
 CLSS public abstract interface com.oracle.truffle.api.bytecode.debug.BytecodeDebugListener
 meth public void afterInstructionExecute(com.oracle.truffle.api.bytecode.Instruction,java.lang.Throwable)
 meth public void afterRootExecute(com.oracle.truffle.api.bytecode.Instruction,java.lang.Object,java.lang.Throwable)

truffle/src/com.oracle.truffle.api.bytecode/snapshot.sigtest

@@ -55,7 +55,7 @@
 
 /**
  * Defines a constant operand for an operation. Constant operands are supported for
- * {@link Operation}, {@link Instrumentation}, and {@link Prolog} operations.
+ * {@link Operation}, {@link Instrumentation}, {@link Yield}, and {@link Prolog} operations.
  * <p>
  * Constant operands have a few benefits:
  * <ul>

truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/ConstantOperand.java

@@ -105,6 +105,19 @@ public ContinuationResult(ContinuationRootNode rootNode, MaterializedFrame frame
         this.result = result;
     }
 
+    /**
+     * Public API for creating a continuation result.
+     * <p>
+     * This method is mainly useful when using {@link Yield custom yield operations} since the
+     * {@link GenerateBytecode#enableYield() built-in yield} creates continuation results
+     * automatically.
+     *
+     * @since 26.0
+     */
+    public static ContinuationResult create(ContinuationRootNode rootNode, MaterializedFrame frame, Object result) {
+        return new ContinuationResult(rootNode, frame, result);
+    }
+
     /**
      * Resumes the continuation.
      * <p>

truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/ContinuationResult.java

@@ -41,6 +41,7 @@
 package com.oracle.truffle.api.bytecode;
 
 import com.oracle.truffle.api.TruffleLanguage;
+import com.oracle.truffle.api.dsl.Bind.DefaultExpression;
 import com.oracle.truffle.api.frame.Frame;
 import com.oracle.truffle.api.frame.FrameDescriptor;
 import com.oracle.truffle.api.nodes.RootNode;
@@ -57,6 +58,7 @@
  *
  * @since 24.2
  */
+@DefaultExpression("$continuationRootNode")
 public abstract class ContinuationRootNode extends RootNode {
 
     /**

truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/ContinuationRootNode.java

@@ -290,12 +290,17 @@
     boolean allowUnsafe() default true;
 
     /**
-     * Whether the generated interpreter should support coroutines via a {@code yield} operation.
+     * Whether the generated interpreter should support coroutines via a built-in {@code yield}
+     * operation.
      * <p>
-     * The yield operation returns a {@link ContinuationResult} from the current point in execution.
-     * The {@link 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.
+     * The built-in yield operation returns a {@link ContinuationResult} from the current point in
+     * execution. The {@link 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.
+     * <p>
+     * If more control over the yield process is required, consider defining a custom {@link Yield}
+     * instead. You can enable built-in and custom yields separately (i.e., {@link #enableYield}
+     * does not need to be {@code true} if you only use a custom yield).
      * <p>
      * Technical note: in theoretical terms, a {@link ContinuationResult} implements an asymmetric
      * stack-less coroutine.

truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/GenerateBytecode.java

@@ -0,0 +1,131 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * The Universal Permissive License (UPL), Version 1.0
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.oracle.truffle.api.bytecode;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import com.oracle.truffle.api.frame.MaterializedFrame;
+import com.oracle.truffle.api.instrumentation.Tag;
+import com.oracle.truffle.api.interop.InteropLibrary;
+import com.oracle.truffle.api.dsl.Bind;
+
+/**
+ * Declares a custom yield operation. A custom yield operation has the same control flow behaviour
+ * as the {@link GenerateBytecode#enableYield built-in yield}, but allows to customize the result
+ * produced. For example, a custom yield can create a guest generator object instead of a
+ * {@link ContinuationResult}, or it can perform custom logic before
+ * {@link ContinuationResult#create(ContinuationRootNode, MaterializedFrame, Object) creating} the
+ * continuation result.
+ * <p>
+ * Below is an example of a custom yield that returns a guest language generator object:
+ *
+ * <pre>
+ * &#64;Yield
+ * public static final class CustomYield {
+ *     &#64;Specialization
+ *     public static Object doYield(Object value, &#64;Bind ContinuationRootNode root, &#64;Bind MaterializedFrame frame) {
+ *         return new MyGeneratorObject(root, frame, value);
+ *     }
+ * }
+ * </pre>
+ *
+ * A custom yield operation has many of the same restrictions and capabilities of a regular
+ * {@link Operation}, with a few differences:
+ * <ul>
+ * <li>It must take zero or one dynamic operand.</li>
+ * <li>It yields a value to the caller, so it must have a return value. The result should be a
+ * {@link InteropLibrary#isValidValue valid interop type}. Typically, the result should encapsulate
+ * the continuation state so that the callee can resume execution at a later time.</li>
+ * <li>It can {@link Bind} a {@link ContinuationRootNode} operand, which can be used to resume
+ * execution at a later time. (Custom yields will typically also {@link Bind} the
+ * {@link MaterializedFrame} to capture the interpreter state, but this is possible in regular
+ * operations.)</li>
+ * </ul>
+ *
+ * Note that {@link GenerateBytecode#enableYield} does not need to be {@code true} to use custom
+ * yields; it is only necessary if you need the built-in yield operation. The built-in yield
+ * operation is semantically equivalent to the following custom yield operation:
+ *
+ * <pre>
+ * &#64;Yield
+ * public static final class BuiltinYield {
+ *     &#64;Specialization
+ *     public static Object doYield(Object result, &#64;Bind ContinuationRootNode root, &#64;Bind MaterializedFrame frame) {
+ *         return ContinuationResult.create(root, frame, result);
+ *     }
+ * }
+ * </pre>
+ *
+ * @since 26.0
+ * @see GenerateBytecode#enableYield()
+ */
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.TYPE})
+public @interface Yield {
+
+    /**
+     * Whether executing this operation should force the uncached interpreter (if enabled) to
+     * transition to cached.
+     *
+     * @since 26.0
+     * @see Operation#forceCached()
+     */
+    boolean forceCached() default false;
+
+    /**
+     * The instrumentation tags that should be implicitly associated with this operation.
+     *
+     * @since 26.0
+     * @see GenerateBytecode#enableTagInstrumentation()
+     */
+    Class<? extends Tag>[] tags() default {};
+
+    /**
+     * Optional documentation for the instrumentation. This documentation is included in the javadoc
+     * for the generated interpreter.
+     *
+     * @since 26.0
+     */
+    String javadoc() default "";
+}

truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/Yield.java

@@ -59,7 +59,7 @@
 public interface BytecodeDebugListener {
 
     /**
-     * Invoked before an instruction is executed. This has a very significant performance cost. Only
+     * Invoked before a root is executed. This has a very significant performance cost. Only
      * override this method temporarily for debugging. This method may be called on partial
      * evaluated code paths.
      *
@@ -69,9 +69,13 @@ default void beforeRootExecute(Instruction enterInstruction) {
     }
 
     /**
-     * Invoked before an instruction is executed. This has a very significant performance cost. Only
-     * override this method temporarily for debugging. This method may be called on partial
-     * evaluated code paths.
+     * Invoked before a root is left. This has a very significant performance cost. Only override
+     * this method temporarily for debugging. This method may be called on partial evaluated code
+     * paths.
+     *
+     * @param returnValue the value returned, or null if an exception was thrown. For yields,
+     *            returnValue is the continuation result or custom yield return value.
+     * @param t the exception thrown, or null if the root is exited normally.
      *
      * @since 24.2
      */