Change lane:join() return values

* when no error is raised in the lane, lane:join() now precedes the lane returned values with true
* lane body is no longer forced to return something when used with join()
* adjusted all relevant unit tests accordingly

17 files changed, 85 insertions, 67 deletions

diff --git a/CHANGES b/CHANGES
index 65077f7..b6bf3d6 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,6 +1,6 @@
 CHANGES:
 
-CHANGE 2: BGe 27-Nov-24
+CHANGE 2: BGe 05-Jun-25
     * Internal changes
         - Lanes is implemented in C++20: thread, condition_variable, mutex, string_view, variant, lambdas, templates, and more!
         - Almost all platform-specific code is gone (only a small bit for thread priority and affinity remains).
@@ -37,11 +37,9 @@ CHANGE 2: BGe 27-Nov-24
                 - name added. Can be used to set the name early (before the lane body calls lane_threadname()).
             - New generator lanes.coro() to start a lane as a coroutine.
             - New __close metamethod that calls join().
-            - lane:join()
-                - Returns nil, error in case of problem.
-                - Forces lane function body must return a non-nil first value on success because of the above.
+            - lane:join() returns nil, error in case of problem, else returns true followed by the lane body return values.
             - lane:get_debug_threadname() renamed get_threadname().
-            - cancel_test() returns "soft"/"hard" instead of true when a cancellation request is active
+            - cancel_test() returns "soft"/"hard" instead of true when a cancellation request is active.
         - Lindas:
             - lanes.linda()
                 - Arguments can be provided in any order.
diff --git a/docs/index.html b/docs/index.html
index be8ad7f..ab8aed2 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -71,7 +71,7 @@
                         </p>
 
                         <p>
-                                This document was revised on 07-May-25, and applies to version <tt>4.0.0</tt>.
+                                This document was revised on 05-Jun-25, and applies to version <tt>4.0.0</tt>.
                         </p>
                 </font>
         </center>
@@ -1156,7 +1156,7 @@
 </p>
 
 <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
-        [...]|[nil,err,stack_tbl]= lane_h:join([timeout])
+        [true, ...]|[nil,err,stack_tbl]= lane_h:join([timeout])
 </pre></td></tr></table>
 
 <p>
@@ -1174,7 +1174,7 @@
                         </ul>
                 </li>
                 <li><tt>nil, "killed"</tt> if forcefully killed.</li>
-                <li>The return values of the lane function. If the first return value is <tt>nil</tt> (or there is no return value), an error is raised, to make sure you can tell timeout and error cases apart from successful return.</li>
+                <li><tt>true [, returned-values]</tt>: The return values of the lane function.</li>
         </ul>
         If the lane handle obtained from <tt>lanes.gen()</tt> is to-be-closed, closing the value will cause a call to <tt>join()</tt>. Since it is implicit, the lane body isn't forced to return non-<tt>nil</tt> in that case.
 </p>
diff --git a/src/lane.cpp b/src/lane.cpp
index 65a776e..cb20930 100644
--- a/src/lane.cpp
+++ b/src/lane.cpp
@@ -105,7 +105,7 @@ static LUAG_FUNC(lane_threadname)
 // #################################################################################################
 
 //---
-// [...] | [nil, err_any, stack_tbl]= lane:join([wait_secs])
+// [true, ...] | [nil, err_any, stack_tbl]= lane:join([wait_secs])
 //
 //  timeout:   returns nil
 //  done:      returns return values (0..N)
@@ -147,18 +147,19 @@ static LUAG_FUNC(lane_join)
     switch (_lane->status.load(std::memory_order_acquire)) {
     case Lane::Suspended: // got yielded values
     case Lane::Done: // got regular return values
-        {
-            if (_stored == 0) {
-                raise_luaL_error(L_, _lane->L ? "First return value must be non-nil when using join()" : "Can't join() more than once or after indexing");
-            }
+        if (_stored > 0) {
             lua_getiuservalue(L_, StackIndex{ 1 }, UserValueIndex{ 1 });                           // L_: lane {uv}
             for (int _i = 2; _i <= _stored; ++_i) {
                 lua_rawgeti(L_, 2, _i);                                                            // L_: lane {uv} results2...N
             }
             lua_rawgeti(L_, 2, 1);                                                                 // L_: lane {uv} results2...N result1
             lua_replace(L_, 2);                                                                    // L_: lane results
-            _ret = _stored;
         }
+        // we precede the lane body returned values with boolean true
+        lua_pushboolean(L_, 1);                                                                    // L_: lane results true
+        lua_replace(L_, 1);                                                                        // L_: true results
+        _ret = _stored + 1;
+        STACK_CHECK(L_, _stored);
         break;
 
     case Lane::Error:
@@ -174,25 +175,30 @@ static LUAG_FUNC(lane_join)
                 lua_replace(L_, 2);                                                                // L_: lane nil <error> <trace>
             }
             _ret = lua_gettop(L_) - 1; // 2 or 3
+            STACK_CHECK(L_, _ret);
         }
         break;
 
     case Lane::Cancelled:
-        LUA_ASSERT(L_, _stored == 2);
-        lua_getiuservalue(L_, StackIndex{ 1 }, UserValueIndex{ 1 });                              // L_: lane {uv}
-        lua_rawgeti(L_, 2, 2);                                                                    // L_: lane {uv} cancel_error
-        lua_rawgeti(L_, 2, 1);                                                                    // L_: lane {uv} cancel_error nil
-        lua_replace(L_, -3);                                                                      // L_: lane nil cancel_error
-        LUA_ASSERT(L_, lua_isnil(L_, -2) && kCancelError.equals(L_, kIdxTop));
-        _ret = 2;
+        {
+            LUA_ASSERT(L_, _stored == 2);
+            lua_getiuservalue(L_, StackIndex{ 1 }, UserValueIndex{ 1 });                           // L_: lane {uv}
+            lua_rawgeti(L_, 2, 2);                                                                 // L_: lane {uv} cancel_error
+            lua_rawgeti(L_, 2, 1);                                                                 // L_: lane {uv} cancel_error nil
+            lua_replace(L_, -3);                                                                   // L_: lane nil cancel_error
+            LUA_ASSERT(L_, lua_isnil(L_, -2) && kCancelError.equals(L_, kIdxTop));
+            _ret = 2;
+            STACK_CHECK(L_, _ret);
+        }
         break;
 
     default:
         DEBUGSPEW_CODE(DebugSpew(nullptr) << "Unknown Lane status: " << static_cast<int>(_lane->status.load(std::memory_order_relaxed)) << std::endl);
         LUA_ASSERT(L_, false);
         _ret = 0;
+        STACK_CHECK(L_, _ret);
     }
-    STACK_CHECK(L_, _ret);
+    LUA_ASSERT(L_, lua_gettop(L_) >= _ret);
     return _ret;
 }
 
diff --git a/tests/appendud.lua b/tests/appendud.lua
index f6f99c1..2a8c8ce 100644
--- a/tests/appendud.lua
+++ b/tests/appendud.lua
@@ -49,7 +49,7 @@ assert(not err)
 -- test
 -- print("t:join()")
 a,b,c = t[1],t[2],t[3]    -- Need to explicitly wait for the thread, since 'ipairs()' does not
---a,b,c = t:join()    -- Need to explicitly wait for the thread, since 'ipairs()' does not
+--r,a,b,c = t:join()    -- Need to explicitly wait for the thread, since 'ipairs()' does not
             -- value the '__index' metamethod (wouldn't it be cool if it did..?)
 
 print(a,b,c)
diff --git a/tests/basic.lua b/tests/basic.lua
index 9aaad97..f393175 100644
--- a/tests/basic.lua
+++ b/tests/basic.lua
@@ -507,19 +507,20 @@ local S = lanes.gen("table", { name = 'auto', gc_cb = gc_cb },
     return (unpack or table.unpack)(aux)
 end)
 
-h= S { 12, 13, 14 }     -- execution starts, h[1..3] will get the return values
+h = S { 12, 13, 14 }     -- execution starts, h[1..3] will get the return values
 -- wait a bit so that the lane has a chance to set its debug name
 SLEEP(0.5)
 print("joining with '" .. h:get_threadname() .. "'")
-local a,b,c,d= h:join()
+local r,a,b,c,d= h:join()
 if h.status == "error" then
-    print(h:get_threadname(), "error: " , a, b, c, d)
+    print(h:get_threadname(), "error: " , r, a, b, c, d)
 else
-    print(h:get_threadname(), a,b,c,d)
-    assert(a==14)
-    assert(b==13)
-    assert(c==12)
-    assert(d==nil)
+    print(h:get_threadname(), r,a,b,c,d)
+    assert(r == true)
+    assert(a == 14)
+    assert(b == 13)
+    assert(c == 12)
+    assert(d == nil)
 end
 
 local nameof_type, nameof_name = lanes.nameof(print)
diff --git a/tests/error.lua b/tests/error.lua
index 28cfff1..76ceea4 100644
--- a/tests/error.lua
+++ b/tests/error.lua
@@ -173,8 +173,7 @@ local do_error_catching_test = function(error_reporting_mode_, error_value_, fin
     local h = start_lane(error_reporting_mode_, error_value_, finalizer_, finalizer_error_value_)

     local ret,err,stack= h:join()   -- wait for the lane (no automatic error propagation)

     WR("Processing results for {", error_reporting_mode_, error_value_, finalizer_, finalizer_error_value_, "}")

-    if err then

-        assert(ret == nil)

+    if ret == nil then

         assert(error_reporting_mode_ == "minimal" or type(stack)=="table") -- only true if lane was configured with error_trace_level ~= "minimal"

         if err == error_value_ then

             WR("Lane regular error: ", err)

@@ -198,8 +197,8 @@ local do_error_catching_test = function(error_reporting_mode_, error_value_, fin
             end

         end

     else -- no error

-        assert(ret == "success")

-        WR("No error in lane: ", ret)

+        assert(ret == true and err == "success")

+        WR("No error in lane: ", err, ret)

     end

     WR "TEST OK"

 end

diff --git a/tests/finalizer.lua b/tests/finalizer.lua
index ac5ce8b..9fa12dc 100644
--- a/tests/finalizer.lua
+++ b/tests/finalizer.lua
@@ -77,8 +77,8 @@ local do_test = function(error_)
 

     local h = lgen(error_)

 

-    local _,err,stack = h:join()   -- wait for the lane (no automatic error propagation)

-    if err then

+    local r,err,stack = h:join()   -- wait for the lane (no automatic error propagation)

+    if not r then

         assert(stack, "no stack trace on error, check 'error_trace_level'")

         io.stderr:write( "Lane error: "..tostring(err).."\n" )

         io.stderr:write( "\t", table.concat(stack,"\t\n"), "\n" )

diff --git a/tests/func_is_string.lua b/tests/func_is_string.lua
index 5de4c60..3c91603 100644
--- a/tests/func_is_string.lua
+++ b/tests/func_is_string.lua
@@ -21,16 +21,17 @@ end
 
 local options = {globals = { b = 666 }}
 
-local gen1 = lanes.gen("*", { name = 'auto' }, "return true, dofile('fibonacci.lua')")
-local gen2 = lanes.gen(options, { name = 'auto' }, "return b")
+local gen1 = lanes.gen("*", { name = 'auto' }, "return true, error('bob')")
 
 fibLane = gen1()
 lanes.sleep(0.1)
 print(fibLane, fibLane.status)
-local _status, _err = fibLane:join()
-print(_status, _err)
+local _r, _err, _stk = fibLane:join()
+assert(_r == nil, "got " .. tostring(_r) .. " " .. tostring(_err) .. " " .. tostring(_stk))
 
-retLane1, retLane2 = gen2(), gen2()
+local gen2 = lanes.gen(options, { name = 'auto' }, "return b")
+local retLane1, retLane2 = gen2(), gen2()
 
 print( retLane1[1], retLane2[1])
-print "TEST OK"
\ No newline at end of file
+assert(retLane1[1] == 666 and retLane2[1] == 666)
+print "TEST OK"
diff --git a/tests/launchtest.lua b/tests/launchtest.lua
index 57411e1..cdd6ffc 100644
--- a/tests/launchtest.lua
+++ b/tests/launchtest.lua
@@ -69,8 +69,8 @@ else
     io.stderr:write( N.." lanes launched.\n" )
     
     for i=1,N do
-        local rc= t[i]:join()
-        assert( rc==i )
+        local r,rc = t[i]:join()
+        assert( r == true and rc == i )
     end
 
     io.stderr:write( N.." lanes finished.\n" )
diff --git a/tests/linda_perf.lua b/tests/linda_perf.lua
index 83b8921..e68d552 100644
--- a/tests/linda_perf.lua
+++ b/tests/linda_perf.lua
@@ -56,7 +56,7 @@ local eater = function( l, loop)
         -- print "loop is over"
         key, val = l:receive( "done")
         print("eater: done ("..val..")")
-        return true
+        return "ate everything"
 end
 
 -- #################################################################################################
@@ -74,7 +74,7 @@ local gobbler = function( l, loop, batch)
         print "loop is over"
         key, val = l:receive( "done")
         print("gobbler: done ("..val..")")
-        return true
+        return "gobbled everything"
 end
 
 -- #################################################################################################
@@ -123,7 +123,8 @@ local function ziva1( preloop, loop, batch)
                 end
         end
         l:send( "done" ,"are you happy?")
-        lane:join()
+        local r, ret = lane:join()
+        assert(r == true and type(ret) == "string", "got " .. tostring(r) .. " " .. tostring(ret))
         return lanes.now_secs() - t1
 end
 
diff --git a/tests/perftest.lua b/tests/perftest.lua
index fe43cca..35e164d 100644
--- a/tests/perftest.lua
+++ b/tests/perftest.lua
@@ -175,9 +175,9 @@ else
     -- Make sure all lanes finished
     --
     for i=1,N do
-        local tmp= t[i]:join()
+        local r, tmp = t[i]:join()
         -- this assert will trigger if you change M to values below 1000 in order to solve C stack overflow
-        assert( type(tmp)=="table" and tmp[1]==2 and tmp[168]==997 )
+        assert( r == true and type(tmp) == "table" and tmp[1] == 2 and tmp[168] == 997 )
     end
 end
 
diff --git a/tests/pingpong.lua b/tests/pingpong.lua
index 06c0903..1ed5b9a 100644
--- a/tests/pingpong.lua
+++ b/tests/pingpong.lua
@@ -21,13 +21,15 @@ local pingpong = function(name, qr, qs, start)
         q:send(qs, val)
         count = count + 1
     end
-    return true
+    return "ping!"
 end
 
 -- pingpong("L1", '0', '1', true)
 local t1, err1 = lanes.gen("*", { name = 'auto' }, pingpong)("L1", 'a', 'b', true)
 local t2, err2 = lanes.gen("*", { name = 'auto' }, pingpong)("L2", 'b', 'a', false)
 
-t1:join()
-t2:join()
+local r1, ret1 = t1:join()
+assert(r1 == true and ret1 == "ping!")
+local r2, ret2 = t2:join()
+assert(r2 == true and ret2 == "ping!")
 print "TEST OK"
diff --git a/tests/rupval.lua b/tests/rupval.lua
index ad5ad9d..c6743b3 100644
--- a/tests/rupval.lua
+++ b/tests/rupval.lua
@@ -26,17 +26,17 @@ end
 local g = lanes.gen( "base", { name = 'auto' }, a)
 
 local l = g(7)
-local r = l:join()
+local _, r = l:join()
 assert(r == y)
 print(r)
 
 local l = g(8)
-local r = l:join()
+local _, r = l:join()
 assert(r == z)
 print(r)
 
 local l = g(9)
-local r = l:join()
+local _, r = l:join()
 assert(r == x)
 print(r)
 
diff --git a/tests/tobeclosed.lua b/tests/tobeclosed.lua
index 447b936..fd157e2 100644
--- a/tests/tobeclosed.lua
+++ b/tests/tobeclosed.lua
@@ -106,7 +106,7 @@ do
         local _count, l_out <close> = l:get("trip")
         -- linda from arguments
         local l_arg <close> = l_arg_
-        return true
+        return "done"
     end
 
     local close_handler_f = function(linda_, err_)
@@ -118,7 +118,8 @@ do
     l:set("trip", l_in)
 
     do
-    lanes.gen("*", { name = 'auto' }, lane_body)(l_in):join()
+        local r, ret = lanes.gen("*", { name = 'auto' }, lane_body)(l_in):join()
+        assert(r == true and ret == "done")
     end
     local _count, _closed = l_in:get("closed")
     assert(_count == 1 and _closed == 2)
diff --git a/unit_tests/scripts/coro/basics.lua b/unit_tests/scripts/coro/basics.lua
index cd2f410..c0b7a36 100644
--- a/unit_tests/scripts/coro/basics.lua
+++ b/unit_tests/scripts/coro/basics.lua
@@ -85,7 +85,8 @@ if true then
     assert(h3:resume(1) == nil)
 
     -- similarly, we can get them with join()
-    assert(h3:join() == "world" and h3.status == "suspended")
+    local r3, ret3 = h3:join()
+    assert(r3 == true and ret3 == "world" and h3.status == "suspended")
     -- since we consumed the returned values, they should not be here when we resume
     assert(h3:resume(2) == nil)
 
@@ -93,5 +94,6 @@ if true then
     assert(h3:resume(3) == "!")
 
     -- the final return value of the lane body remains to be read
-    assert(h3:join() == "done!" and h3.status == "done")
+    local r3, ret3 = h3:join()
+    assert(r3 == true and ret3 == "done!" and h3.status == "done")
 end
diff --git a/unit_tests/scripts/lane/tasking_join_test.lua b/unit_tests/scripts/lane/tasking_join_test.lua
index 2fbce6c..495a709 100644
--- a/unit_tests/scripts/lane/tasking_join_test.lua
+++ b/unit_tests/scripts/lane/tasking_join_test.lua
@@ -30,14 +30,19 @@ end
 
 PRINT("---=== :join test ===---", "\n\n")
 
+-- a lane body that returns nothing is successfully joined with true, nil
+local r, ret = lanes_gen(function() end)():join()
+assert(r == true and ret == nil)
+
 -- NOTE: 'unpack()' cannot be used on the lane handle; it will always return nil
 --       (unless [1..n] has been read earlier, in which case it would seemingly
 --       work).
 
-local S= lanes_gen("table", { name = 'auto', gc_cb = gc_cb },
+local S = lanes_gen("table", { name = 'auto', gc_cb = gc_cb },
     function(arg)
         lane_threadname "join test lane"
         set_finalizer(function() end)
+        -- take arg table, reverse its contents in aux, then return the unpacked result
         local aux= {}
         for i, v in ipairs(arg) do
            table.insert(aux, 1, v)
@@ -46,15 +51,16 @@ local S= lanes_gen("table", { name = 'auto', gc_cb = gc_cb },
     return (unpack or table.unpack)(aux)
 end)
 
-h= S { 12, 13, 14 }     -- execution starts, h[1..3] will get the return values
+local h = S { 12, 13, 14 }     -- execution starts, h[1..3] will get the return values
 -- wait a bit so that the lane has a chance to set its debug name
 SLEEP(0.5)
 print("joining with '" .. h:get_threadname() .. "'")
-local a,b,c,d= h:join()
+local r, a, b, c, d = h:join()
 if h.status == "error" then
-    print(h:get_threadname(), "error: " , a, b, c, d)
+    print(h:get_threadname(), "error: " , r, a, b, c, d)
 else
-    print(h:get_threadname(), a,b,c,d)
+    print(h:get_threadname(), r, a, b, c, d)
+    assert(r==true, "r == " .. tostring(r))
     assert(a==14, "a == " .. tostring(a))
     assert(b==13, "b == " .. tostring(b))
     assert(c==12, "c == " .. tostring(c))
diff --git a/unit_tests/scripts/linda/wake_period.lua b/unit_tests/scripts/linda/wake_period.lua
index e4a900d..d2dccc3 100644
--- a/unit_tests/scripts/linda/wake_period.lua
+++ b/unit_tests/scripts/linda/wake_period.lua
@@ -6,7 +6,7 @@ local lanes = require_lanes_result_1
 local body = function(linda_)
         -- a blocking read that lasts longer than the tested wake_period values
         linda_:receive(2, "empty_slot")
-        return true
+        return "done"
 end
 
 -- if we don't cancel the lane, we should wait the whole duration
@@ -22,7 +22,8 @@ local function check_wake_duration(linda_, expected_, do_cancel_)
                 assert(result == false and reason == 'timeout', "unexpected cancel result")
         end
         -- this should wait until the linda wakes by itself before the actual receive timeout and sees the cancel request
-        h:join()
+        local r, ret = h:join()
+        assert(r == true and ret == "done")
         local t1 = lanes.now_secs()
         local delta = t1 - t0
         -- the linda should check for cancellation at about the expected period, not earlier