Fix getTrace() to use ZEND_COROUTINE_SUSPENDED macro, return null instead of empty array, and fix tests to use suspend()

Co-authored-by: EdmondDantes <1571649+EdmondDantes@users.noreply.github.com>

Author: Copilot

coroutine.c

@@ -1344,13 +1344,17 @@ METHOD(getTrace)
 	ZEND_PARSE_PARAMETERS_END();
 
 	async_coroutine_t *coroutine = THIS_COROUTINE;
+
+	// Return null if coroutine is not suspended
+	if (!ZEND_COROUTINE_SUSPENDED(&coroutine->coroutine)) {
+		RETURN_NULL();
+	}
+
 	async_fiber_context_t *fiber_context = coroutine->fiber_context;
 
-	// Return empty array if coroutine is not suspended or has no fiber context
-	if (fiber_context == NULL ||
-		(fiber_context->context.status != ZEND_FIBER_STATUS_SUSPENDED || !fiber_context->execute_data)) {
-		array_init(return_value);
-		return;
+	// Additional safety check for fiber context
+	if (fiber_context == NULL || !fiber_context->execute_data) {
+		RETURN_NULL();
 	}
 
 	// Switch to the coroutine's VM stack to generate the backtrace

coroutine.stub.php

@@ -43,12 +43,12 @@ public function getException(): mixed {}
     /**
      * Returns the Coroutine debug trace.
      * If the coroutine is in the suspended state, returns a backtrace array.
-     * Otherwise, returns an empty array.
+     * Otherwise, returns null.
      *
      * @param int $options Options for the backtrace (DEBUG_BACKTRACE_PROVIDE_OBJECT, DEBUG_BACKTRACE_IGNORE_ARGS)
      * @param int $limit Maximum number of stack frames to return (0 for no limit)
      */
-    public function getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): array {}
+    public function getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): ?array {}
 
     /**
      * Return spawn file and line.

coroutine_arginfo.h

@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 35d332163bf92ed3cad35c83017aaa67d650aa9d */
+ * Stub hash: 2469ab708f75ecce11e559548c2462562fd39c2a */
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_class_Async_Coroutine_getId, 0, 0, IS_LONG, 0)
 ZEND_END_ARG_INFO()
@@ -15,7 +15,7 @@ ZEND_END_ARG_INFO()
 
 #define arginfo_class_Async_Coroutine_getException arginfo_class_Async_Coroutine_getResult
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_class_Async_Coroutine_getTrace, 0, 0, IS_ARRAY, 0)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_class_Async_Coroutine_getTrace, 0, 0, IS_ARRAY, 1)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, options, IS_LONG, 0, "DEBUG_BACKTRACE_PROVIDE_OBJECT")
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, limit, IS_LONG, 0, "0")
 ZEND_END_ARG_INFO()

tests/coroutine/009-coroutine_getTrace.phpt

@@ -1,5 +1,5 @@
 --TEST--
-Coroutine: getTrace() - returns empty array for non-suspended coroutine
+Coroutine: getTrace() - returns null for non-suspended coroutine
 --FILE--
 <?php
 
@@ -10,30 +10,28 @@ $coroutine = spawn(function() {
     return "test";
 });
 
+// Before the coroutine starts, trace should be null
+$traceBeforeStart = $coroutine->getTrace();
+echo "Trace before start is null: " . ($traceBeforeStart === null ? "yes" : "no") . "\n";
+
 // Wait for coroutine to complete
 await($coroutine);
 
-// After completion, trace should be empty
+// After completion, trace should be null
 $trace = $coroutine->getTrace();
+echo "Trace after completion is null: " . ($trace === null ? "yes" : "no") . "\n";
 
-var_dump(is_array($trace));
-var_dump(count($trace));
-
-// Test with options parameter
+// Test with options parameter - should still return null
 $trace2 = $coroutine->getTrace(DEBUG_BACKTRACE_IGNORE_ARGS);
-var_dump(is_array($trace2));
-var_dump(count($trace2));
+echo "Trace with IGNORE_ARGS is null: " . ($trace2 === null ? "yes" : "no") . "\n";
 
-// Test with limit parameter
+// Test with limit parameter - should still return null
 $trace3 = $coroutine->getTrace(DEBUG_BACKTRACE_PROVIDE_OBJECT, 5);
-var_dump(is_array($trace3));
-var_dump(count($trace3));
+echo "Trace with limit is null: " . ($trace3 === null ? "yes" : "no") . "\n";
 
 ?>
 --EXPECT--
-bool(true)
-int(0)
-bool(true)
-int(0)
-bool(true)
-int(0)
+Trace before start is null: yes
+Trace after completion is null: yes
+Trace with IGNORE_ARGS is null: yes
+Trace with limit is null: yes

tests/coroutine/037-coroutine_getTrace_suspended.phpt

@@ -4,41 +4,62 @@ Coroutine: getTrace() - returns backtrace for suspended coroutine
 <?php
 
 use function Async\spawn;
+use function Async\suspend;
 use function Async\await;
 
-$coroutine = spawn(function() {
-    // This function will suspend
-    Async\sleep(0.1);
-    return "test";
-});
-
-// Get trace while coroutine is suspended
-$trace = $coroutine->getTrace();
-
-var_dump(is_array($trace));
-echo "Trace has entries: " . (count($trace) > 0 ? "yes" : "no") . "\n";
-
-// Test with DEBUG_BACKTRACE_IGNORE_ARGS
-$traceNoArgs = $coroutine->getTrace(DEBUG_BACKTRACE_IGNORE_ARGS);
-var_dump(is_array($traceNoArgs));
+$parentCoroutine = null;
+$childCoroutine = null;
 
-// Test with limit
-$traceLimited = $coroutine->getTrace(DEBUG_BACKTRACE_PROVIDE_OBJECT, 2);
-var_dump(is_array($traceLimited));
-
-// Wait for coroutine to complete
-await($coroutine);
-
-// After completion, trace should be empty
-$traceAfter = $coroutine->getTrace();
-var_dump(is_array($traceAfter));
-var_dump(count($traceAfter) === 0);
+// Spawn a parent coroutine
+$parentCoroutine = spawn(function() use (&$childCoroutine) {
+    echo "Parent: Starting\n";
+    
+    // Spawn a child coroutine that will suspend
+    $childCoroutine = spawn(function() {
+        echo "Child: Before suspend\n";
+        suspend();
+        echo "Child: After suspend\n";
+    });
+    
+    // Suspend to let child start and suspend
+    suspend();
+    
+    echo "Parent: Back from suspend\n";
+    
+    // Now check child's trace while it's suspended
+    $trace = $childCoroutine->getTrace();
+    
+    if ($trace !== null) {
+        echo "Child trace is array: " . (is_array($trace) ? "yes" : "no") . "\n";
+        echo "Child trace has entries: " . (count($trace) > 0 ? "yes" : "no") . "\n";
+        
+        // Test with DEBUG_BACKTRACE_IGNORE_ARGS
+        $traceNoArgs = $childCoroutine->getTrace(DEBUG_BACKTRACE_IGNORE_ARGS);
+        echo "Trace with IGNORE_ARGS is array: " . (is_array($traceNoArgs) ? "yes" : "no") . "\n";
+        
+        // Test with limit
+        $traceLimited = $childCoroutine->getTrace(DEBUG_BACKTRACE_PROVIDE_OBJECT, 2);
+        echo "Trace with limit is array: " . (is_array($traceLimited) ? "yes" : "no") . "\n";
+    } else {
+        echo "Child trace is null\n";
+    }
+    
+    // Resume to let child finish
+    suspend();
+    
+    // After completion, trace should be null
+    $traceAfter = $childCoroutine->getTrace();
+    echo "Child trace after completion is null: " . ($traceAfter === null ? "yes" : "no") . "\n";
+});
 
 ?>
---EXPECTF--
-bool(true)
-Trace has entries: %s
-bool(true)
-bool(true)
-bool(true)
-bool(true)
+--EXPECT--
+Parent: Starting
+Child: Before suspend
+Parent: Back from suspend
+Child trace is array: yes
+Child trace has entries: yes
+Trace with IGNORE_ARGS is array: yes
+Trace with limit is array: yes
+Child: After suspend
+Child trace after completion is null: yes