Simplify resume API

Signed-off-by: Maksym Pavlenko <pavlenko.maksym@gmail.com>

Author: mxpv

examples/guided_tour.zig

@@ -13,6 +13,7 @@
 //! - Push and retrieve arrays
 //! - Work with tuples and table-based structures
 //! - Control garbage collection for memory management
+//! - Work with coroutines and threads
 
 const std = @import("std");
 const luaz = @import("luaz");
@@ -573,5 +574,42 @@ pub fn main() !void {
         , .{}, void);
     }
 
+    // Coroutines and threads
+    {
+        print("\n-- Coroutines and Threads --\n", .{});
+
+        // Create a coroutine function in global scope
+        _ = try lua.eval(
+            \\function accumulator()
+            \\    local sum = 0
+            \\    while true do
+            \\        local value = coroutine.yield(sum)
+            \\        if value == nil then break end
+            \\        sum = sum + value
+            \\    end
+            \\    return sum
+            \\end
+        , .{}, void);
+
+        const thread = lua.createThread();
+        const func = try thread.globals().get("accumulator", luaz.Lua.Function);
+        defer func.?.deinit();
+
+        // Start the coroutine - yields initial sum (0)
+        const result1 = try func.?.call(.{}, i32);
+        print("Start: sum={}\n", .{result1});
+
+        // Continue with values to accumulate
+        const result2 = try func.?.call(.{10}, i32);
+        print("Add 10: sum={}\n", .{result2});
+
+        const result3 = try func.?.call(.{25}, i32);
+        print("Add 25: sum={}\n", .{result3});
+
+        // Send nil to finish
+        const final_result = try func.?.call(.{@as(?i32, null)}, i32);
+        print("Final: sum={}\n", .{final_result});
+    }
+
     print("\n=== Tour Complete! ===\n", .{});
 }

src/lua.zig

@@ -861,6 +861,10 @@ pub const Lua = struct {
         /// Pushes the function onto the stack, followed by the arguments, then calls the function
         /// and returns the result converted to the specified type.
         ///
+        /// NOTE: When called on a function in a thread (created with
+        /// `createThread()`), this method automatically uses resume semantics, allowing the
+        /// function to yield. In the main state, it uses regular call semantics.
+        ///
         /// Examples:
         /// ```zig
         /// // Call a function with no arguments
@@ -871,6 +875,15 @@ pub const Lua = struct {
         ///
         /// // Call a function returning multiple values
         /// const result = try func.call(.{}, struct { f64, f64 });
+        ///
+        /// // Coroutine example - function can yield
+        /// const thread = lua.createThread();
+        /// const func = try thread.globals().get("coroutine_func", Function).?;
+        /// defer func.deinit();
+        ///
+        /// const result1 = try func.call(.{}, i32);     // Start coroutine, may yield
+        /// const result2 = try func.call(.{5}, i32);    // Continue coroutine with arg 5
+        /// const result3 = try func.call(.{}, i32);     // Final result
         /// ```
         ///
         /// Errors: `Error.OutOfMemory` if stack allocation fails, `Error.Runtime` if function execution fails
@@ -879,7 +892,9 @@ pub const Lua = struct {
 
             stack.push(self.ref.lua, self.ref); // Push function ref
 
-            const result = self.ref.lua.call(args, R, false);
+            // Use resume semantics if in a thread, call semantics if in main state
+            const result = self.ref.lua.call(args, R, self.ref.lua.isThread());
+
             return switch (result.status) {
                 .ok, .yield => result.result.?,
                 .errmem => error.OutOfMemory,
@@ -1002,43 +1017,6 @@ pub const Lua = struct {
         };
     }
 
-    /// Resume a coroutine with the given arguments and return type.
-    ///
-    /// This method resumes execution of a suspended coroutine (thread) that was previously
-    /// yielded. It's designed to work with threads created by createThread().
-    ///
-    /// **Important**: This method should only be called on thread objects created with
-    /// `createThread()`. Calling `resume_()` on the main Lua state will return an error
-    /// status (`.errrun`) with a null result, as the main thread cannot be resumed.
-    ///
-    /// Parameters:
-    /// - `args`: Arguments to pass to the resumed coroutine (can be tuple, single value, or void)
-    /// - `R`: Compile-time return type expected from the coroutine
-    ///
-    /// Returns:
-    /// A struct containing both the execution status and the result:
-    /// - `.status`: The execution status (.ok, .yield, .errrun, etc.)
-    /// - `.result`: The value returned/yielded by the coroutine (null for errors)
-    ///
-    /// Example:
-    /// ```zig
-    /// const thread_lua = lua.createThread();
-    /// _ = try thread_lua.eval("function coro() coroutine.yield(42); return 100 end; return coro()", .{}, void);
-    ///
-    /// const result1 = thread_lua.resume_(.{}, i32);  // Yields 42
-    /// if (result1.result) |value| std.debug.print("Yielded: {}\n", .{value}); // Prints: Yielded: 42
-    ///
-    /// const result2 = thread_lua.resume_(.{}, i32);  // Returns 100
-    /// if (result2.result) |value| std.debug.print("Returned: {}\n", .{value}); // Prints: Returned: 100
-    ///
-    /// // Error case - trying to resume main thread:
-    /// const main_result = lua.resume_(.{}, void);  // lua is main thread
-    /// if (main_result.status == .errrun) std.debug.print("Cannot resume main thread\n", .{});
-    /// ```
-    pub fn resume_(self: Self, args: anytype, comptime R: type) CallResult(R) {
-        return self.call(args, R, true);
-    }
-
     /// Get the current status of this coroutine thread.
     ///
     /// Returns the execution state of the coroutine without resuming it.
@@ -1174,7 +1152,7 @@ pub const Lua = struct {
     }
 
     /// Calls (or resumes) a Lua function with the provided arguments and returns the result.
-    fn call(self: Self, args: anytype, comptime R: type, comptime is_resume: bool) CallResult(R) {
+    fn call(self: Self, args: anytype, comptime R: type, is_resume: bool) CallResult(R) {
         // Count and push args - unified logic for both call types
         const arg_count = blk: {
             const args_type_info = @typeInfo(@TypeOf(args));

src/tests.zig

@@ -1126,27 +1126,23 @@ test "coroutine yield and resume" {
     , .{}, void);
 
     // Create thread - it shares the global environment
-    const thread_lua = lua.createThread();
+    const thread = lua.createThread();
 
     // Load function onto thread stack and start coroutine
-    const func = try thread_lua.globals().get("yielder", Lua.Function);
+    const func = try thread.globals().get("yielder", Lua.Function);
     defer func.?.deinit();
-    stack.push(thread_lua, func.?);
 
     // First resume - should yield 1
-    const result1 = thread_lua.resume_(.{}, i32);
-    try expectEq(result1.status, .yield);
-    try expectEq(result1.result.?, 1);
+    const result1 = try func.?.call(.{}, i32);
+    try expectEq(result1, 1);
 
     // Second resume - should yield 2
-    const result2 = thread_lua.resume_(.{}, i32);
-    try expectEq(result2.status, .yield);
-    try expectEq(result2.result.?, 2);
+    const result2 = try func.?.call(.{}, i32);
+    try expectEq(result2, 2);
 
     // Third resume - should return 3 and finish
-    const result3 = thread_lua.resume_(.{}, i32);
-    try expectEq(result3.status, .ok);
-    try expectEq(result3.result.?, 3);
+    const result3 = try func.?.call(.{}, i32);
+    try expectEq(result3, 3);
 }
 
 test "coroutine with arguments on yield" {
@@ -1173,27 +1169,22 @@ test "coroutine with arguments on yield" {
 
     const func = try thread.globals().get("accumulator", Lua.Function);
     defer func.?.deinit();
-    stack.push(thread, func.?);
-
-    // First resume - starts the coroutine, yields 0
-    const result1 = thread.resume_(.{}, i32);
-    try expectEq(result1.status, .yield);
-    try expectEq(result1.result.?, 0);
-
-    // Resume with value 5
-    const result2 = thread.resume_(5, i32);
-    try expectEq(result2.status, .yield);
-    try expectEq(result2.result.?, 5);
-
-    // Resume with value 10
-    const result3 = thread.resume_(10, i32);
-    try expectEq(result3.status, .yield);
-    try expectEq(result3.result.?, 15);
-
-    // Resume with nil to finish
-    const result4 = thread.resume_(@as(?i32, null), i32);
-    try expectEq(result4.status, .ok);
-    try expectEq(result4.result.?, 15);
+
+    // Start the coroutine - yields 0
+    const result1_value = try func.?.call(.{}, i32);
+    try expectEq(result1_value, 0);
+
+    // Continue the coroutine with value 5
+    const result2_value = try func.?.call(.{5}, i32);
+    try expectEq(result2_value, 5);
+
+    // Continue the coroutine with value 10
+    const result3_value = try func.?.call(.{10}, i32);
+    try expectEq(result3_value, 15);
+
+    // Finish the coroutine with nil
+    const result4_value = try func.?.call(.{@as(?i32, null)}, i32);
+    try expectEq(result4_value, 15);
 }
 
 test "thread data via globals" {
@@ -1277,11 +1268,9 @@ test "simple thread function execution" {
     // Load and run function in thread
     const func = try thread_lua.globals().get("simple", Lua.Function);
     defer func.?.deinit();
-    stack.push(thread_lua, func.?);
 
-    const result = thread_lua.resume_(.{}, i32);
-    try expectEq(result.status, .ok);
-    try expectEq(result.result.?, 42);
+    const result = try func.?.call(.{}, i32);
+    try expectEq(result, 42);
 }
 
 test "coroutine error handling" {
@@ -1301,12 +1290,10 @@ test "coroutine error handling" {
 
     const func = try thread_lua.globals().get("error_coro", Lua.Function);
     defer func.?.deinit();
-    stack.push(thread_lua, func.?);
 
-    // Resume should return error status
-    const error_result = thread_lua.resume_(.{}, void);
-    try expectEq(error_result.status, .errrun);
-    try expect(error_result.result == null);
+    // Resume should return error
+    const error_result = func.?.call(.{}, void);
+    try std.testing.expectError(error.Runtime, error_result);
 }
 
 test "resume from main thread should return error" {
@@ -1316,10 +1303,19 @@ test "resume from main thread should return error" {
     // Verify this is the main thread
     try expect(!lua.isThread());
 
-    // Try to resume the main thread - this should fail
-    const result = lua.resume_(.{}, void);
+    // Create a simple function (not a coroutine)
+    _ = try lua.eval(
+        \\function test_func()
+        \\    return 42
+        \\end
+    , .{}, void);
 
-    // Should return .errrun status (cannot resume dead coroutine)
-    try expectEq(result.status, .errrun);
-    try expect(result.result == null);
+    // In main thread, functions are called with pcall semantics, not resume
+    // This is tested implicitly - Function.call() automatically detects thread context
+    const func = try lua.globals().get("test_func", Lua.Function);
+    defer func.?.deinit();
+
+    // This will use pcall since we're in main thread
+    const result = try func.?.call(.{}, i32);
+    try expectEq(result, 42);
 }