Fix more issues related to suspended coroutines and join/indexing operations

* indexing and joining a suspended lane closes the coroutine, causing the termination of the lane
* properly close coroutine to-be-closed variables on interruption

5 files changed, 269 insertions, 162 deletions

diff --git a/docs/index.html b/docs/index.html
index ebb93d3..f6201cc 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -71,7 +71,7 @@
                         </p>
 
                         <p>
-                                This document was revised on 26-Jun-25, and applies to version <tt>4.0.0</tt>.
+                                This document was revised on 03-Jul-25, and applies to version <tt>4.0.0</tt>.
                         </p>
                 </font>
         </center>
@@ -922,8 +922,9 @@
                 </tr>
         </table>
 
-        Coroutine lanes function mostly like regular coroutines. They can use <tt>coroutine.yield()</tt> normally, in which case the yielded values can be obtained with regular lane indexing (see <a href="#results">Results and errors</a>).<br />
-        A yielded coroutine lane has a <tt>"suspended"</tt> status. It can be resumed with <tt>lane_h:resume(values...)</tt>.
+        Coroutine lanes function mostly like regular coroutines. They can use <tt>coroutine.yield()</tt> normally.<br />
+        A yielded coroutine lane has a <tt>"suspended"</tt> status. It can be resumed with <tt>lane_h:resume(values...), which returns the yielded values</tt>.
+        The latter can also be the returned values of <tt>lane_h:join()</tt> or accessed by regular lane indexing (see <a href="#results">Results and errors</a>).<br />
         <table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%">
                 <tr>
                         <td>
@@ -932,8 +933,8 @@
                 </tr>
         </table>
 
-        The reply values are returned to the lane body at the <tt>coroutine.yield()</tt> point.<br />
-        If the yielded values were previously obtained by lane indexing, <tt>resume()</tt> returns <tt>nil</tt>.
+        Just like regulare coroutines, the reply values passed to <tt>h:resume()</tt> are returned to the lane body at the <tt>coroutine.yield()</tt> point.<br />
+        If a coroutine lane is suspended when it is joined either by indexing or <tt>lane_h:join()</tt>, active to-be-closed variables are closed at that point, and the Lane can no longer be resumed.
 </p>
 <h3>Free running lanes</h3>
 
diff --git a/src/lane.cpp b/src/lane.cpp
index 5ec6bcf..33ee8a0 100644
--- a/src/lane.cpp
+++ b/src/lane.cpp
@@ -130,93 +130,18 @@ static LUAG_FUNC(lane_join)
     }
     lua_settop(L_, 1);                                                                             // L_: lane
 
-
     // wait until suspended or done
-    bool const _done{ !_lane->thread.joinable() || _lane->waitForCompletion(_until, true) };
-
-    if (!_done) {
-        lua_pushnil(L_);                                                                           // L_: lane nil
-        luaG_pushstring(L_, "timeout");                                                            // L_: lane nil "timeout"
+    STACK_CHECK_START_REL(L_, 0);                                                                  // L_: lane
+    if (!_lane->waitForJoin(L_, _until)) {
+        // in that case, should have pushed nil, "timeout"
+        STACK_CHECK(L_, 2);
         return 2;
     }
+    STACK_CHECK(L_, 0);                                                                            // L_: lane
+    // Thread is Done/Error/Cancelled; the Lane thread isn't working with it, therefore we can.
 
-    // if lane is suspended, force a cancellation that will cause the yield loop to break, and the termination of the thread
-    if (_lane->status.load(std::memory_order_acquire) == Lane::Suspended) {
-        auto const _cr{ _lane->cancel(CancelOp{ CancelRequest::Soft, LuaHookMask::None }, std::chrono::time_point<std::chrono::steady_clock>::max(), WakeLane::Yes, 0) };
-        if (_cr == CancelResult::Timeout) {
-            lua_pushnil(L_);                                                                       // L_: lane nil
-            luaG_pushstring(L_, "timeout");                                                        // L_: lane nil "timeout"
-            return 2;
-        }
-        if (_lane->status.load(std::memory_order_acquire) == Lane::Suspended) {
-            raise_luaL_error(L_, "INTERNAL ERROR: Lane should not be suspended here");
-        }
-    }
-
-    STACK_CHECK_START_REL(L_, 0);                                                                  // L_: lane
-    // Thread is Suspended or Done/Error/Cancelled; the Lane thread isn't working with it, therefore we can.
-
-    int _ret{ 0 };
-    int const _stored{ _lane->storeResults(L_) };
-    STACK_GROW(L_, std::max(3, _stored + 1));
-    switch (_lane->status.load(std::memory_order_acquire)) {
-    case Lane::Suspended:
-        raise_luaL_error(L_, "INTERNAL ERROR: SHOULD NEVER BE SUSPENDED HERE");
-        break;
-
-    case Lane::Done: // got regular return values
-        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
-        }
-        // 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:
-        {
-            LUA_ASSERT(L_, _stored == 2 || _stored == 3);
-            lua_getiuservalue(L_, StackIndex{ 1 }, UserValueIndex{ 1 });                           // L_: lane {uv}
-            lua_rawgeti(L_, 2, 2);                                                                 // L_: lane {uv} <error>
-            lua_rawgeti(L_, 2, 3);                                                                 // L_: lane {uv} <error> <trace>|nil
-            if (lua_isnil(L_, -1)) {
-                lua_replace(L_, 2);                                                                // L_: lane nil <error>
-            } else {
-                lua_rawgeti(L_, 2, 1);                                                             // L_: lane {uv} <error> <trace> nil
-                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;
-            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);
-    }
-    LUA_ASSERT(L_, lua_gettop(L_) >= _ret);
+    std::ignore = _lane->storeResults(L_);
+    int const _ret{ _lane->pushStoredResults(L_) };
     return _ret;
 }
 
@@ -277,13 +202,17 @@ static int lane_index_number(lua_State* L_)
     int const _key{ static_cast<int>(lua_tointeger(L_, 2)) };
     lua_pop(L_, 1);                                                                                // L_: lane
 
-    // wait until the lane finishes or is suspended
+    // wait until suspended or done
+    STACK_CHECK_START_REL(L_, 0);                                                                  // L_: lane
     std::chrono::time_point<std::chrono::steady_clock> _until{ std::chrono::time_point<std::chrono::steady_clock>::max() };
-    if (!_lane->waitForCompletion(_until, true)) {
-        raise_luaL_error(L_, "INTERNAL ERROR: Failed to join");
+    if (!_lane->waitForJoin(L_, _until)) {
+        // in that case, should have pushed nil, "timeout"
+        STACK_CHECK(L_, 2);
+        return 2;
     }
+    STACK_CHECK(L_, 0);                                                                            // L_: lane
+    // Thread is Done/Error/Cancelled; the Lane thread isn't working with it, therefore we can.
 
-    // make sure results are stored
     int const _stored{ _lane->storeResults(L_) };
     if (_key > _stored) {
         // get nil if indexing beyond the actual returned value count
@@ -741,7 +670,7 @@ static void lane_main(Lane* const lane_)
             lane_->nresults = lua_gettop(_L) - _errorHandlerCount;
         } else {
             // S and L are different: we run as a coroutine in Lua thread L created in state S
-            bool _again{ true };
+            bool _shouldClose{ false };
             do {
                 // starting with Lua 5.4, lua_resume can leave more stuff on the stack below the actual yielded values.
                 // that's why we have lane_->nresults
@@ -754,19 +683,25 @@ static void lane_main(Lane* const lane_)
                         lane_->status.store(Lane::Suspended, std::memory_order_release); // Running -> Suspended
                         lane_->doneCondVar.notify_one();
                         // wait until the user wants us to resume
-                        // update waiting_on, so that the lane can be woken by cancellation requests here?
+                        // update waiting_on, so that the lane can be woken by cancellation requests here
                         lane_->waiting_on = &lane_->doneCondVar;
-                        lane_->doneCondVar.wait(_guard, [lane_]() { return lane_->status.load(std::memory_order_acquire) == Lane::Resuming || lane_->cancelRequest.load(std::memory_order_relaxed) != CancelRequest::None; });
+                        lane_->doneCondVar.wait(_guard,
+                            [lane_,&_shouldClose]()
+                            {
+                                auto const _status{ lane_->status.load(std::memory_order_acquire) };
+                                // wait interrupted because of a cancellation or join request means we have to abort the resume loop
+                                _shouldClose = (_status == Lane::Closing);
+                                return _shouldClose || (_status == Lane::Resuming) || (lane_->cancelRequest.load(std::memory_order_relaxed) != CancelRequest::None);
+                            }
+                        );
                         // here lane_->doneMutex is locked again
                         lane_->waiting_on = nullptr;
                         lane_->status.store(Lane::Running, std::memory_order_release); // Resuming -> Running
                     }
-                    // wait was interrupted because of a cancellation, finish the lane
-                    _again = (lane_->cancelRequest.load(std::memory_order_relaxed) == CancelRequest::None);
                 } else {
-                    _again = false;
+                    _shouldClose = true;
                 }
-            } while (_again);
+            } while (!_shouldClose);
             if (_rc == LuaError::YIELD) {
 #if LUA_VERSION_NUM >= 504
                 lua_State* const _S{ lane_->S };
@@ -855,7 +790,7 @@ static void lane_main(Lane* const lane_)
 #if LUA_VERSION_NUM >= 504
 
 // __close(lane_ud, <err>)
-static LUAG_FUNC(lane___close)
+static LUAG_FUNC(lane_close)
 {
     [[maybe_unused]] Lane* const _lane{ ToLane(L_, StackIndex{ 1 }) };                             // L_: lane err|nil
     // drop the error if any
@@ -869,15 +804,6 @@ static LUAG_FUNC(lane___close)
     return lua_gettop(L_);
 }
 
-// #################################################################################################
-
-// close(lane_ud)
-static LUAG_FUNC(lane_close)
-{
-    [[maybe_unused]] Lane* const _lane{ ToLane(L_, StackIndex{ 1 }) };                             // L_: lane err|nil
-    raise_luaL_error(L_, "not implemented"); // TODO!
-    return 0;
-}
 #endif // LUA_VERSION_NUM >= 504
 
 // #################################################################################################
@@ -1069,14 +995,11 @@ namespace {
     namespace local {
         static struct luaL_Reg const sLaneFunctions[] = {
 #if LUA_VERSION_NUM >= 504
-            { "__close", LG_lane___close },
+            { "__close", LG_lane_close },
 #endif // LUA_VERSION_NUM >= 504
             { "__gc", LG_lane_gc },
             { "__index", LG_lane_index },
             { "cancel", LG_lane_cancel },
-#if LUA_VERSION_NUM >= 504
-            { "close", LG_lane_close },
-#endif // LUA_VERSION_NUM >= 504
             { "get_threadname", LG_lane_get_threadname },
             { "join", LG_lane_join },
             { "resume", LG_lane_resume },
@@ -1171,6 +1094,82 @@ void Lane::pushIndexedResult(lua_State* const L_, int const key_) const
 // #################################################################################################
 
 [[nodiscard]]
+int Lane::pushStoredResults(lua_State* const L_) const
+{
+    STACK_CHECK_START_ABS(L_, 1); // should only have the lane UD on the stack
+    static constexpr StackIndex kIdxSelf{ 1 };
+    static constexpr UserValueIndex kUvResults{ 1 };
+    LUA_ASSERT(L_, ToLane(L_, kIdxSelf) == this);                                                  // L_: lane
+    lua_getiuservalue(L_, kIdxSelf, kUvResults);                                                   // L_: lane {uv}
+    lua_rawgeti(L_, kIdxTop, 0);                                                                   // L_: lane {uv} stored
+    int const _stored{ static_cast<int>(lua_tointeger(L_, kIdxTop)) };
+    lua_pop(L_, 1);                                                                                // L_: lane {uv}
+
+    int _ret{};
+    STACK_GROW(L_, std::max(3, _stored + 1));
+    switch (status.load(std::memory_order_acquire)) {
+    case Lane::Suspended:
+        raise_luaL_error(L_, "INTERNAL ERROR: SHOULD NEVER BE SUSPENDED HERE");
+        break;
+
+    case Lane::Done: // got regular return values
+        if (_stored > 0) {
+            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
+        } else {
+            lua_pop(L_, 1);                                                                        // L_: lane
+        }
+        // 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_, _ret);
+        break;
+
+    case Lane::Error:
+        {
+            LUA_ASSERT(L_, _stored == 2 || _stored == 3); // contains nil error [trace]
+            lua_rawgeti(L_, 2, 2);                                                                 // L_: lane {uv} <error>
+            lua_rawgeti(L_, 2, 3);                                                                 // L_: lane {uv} <error> <trace>|nil
+            if (lua_isnil(L_, -1)) {
+                lua_replace(L_, 2);                                                                // L_: lane nil <error>
+            } else {
+                lua_rawgeti(L_, 2, 1);                                                             // L_: lane {uv} <error> <trace> nil
+                lua_replace(L_, 2);                                                                // L_: lane nil <error> <trace>
+            }
+            _ret = _stored; // 2 or 3
+            STACK_CHECK(L_, _ret + 1); // stack still contains the lane UD below
+        }
+        break;
+
+    case Lane::Cancelled:
+        {
+            LUA_ASSERT(L_, _stored == 2);
+            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 + 1); // stack still contains the lane UD below
+        }
+        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);
+    }
+    LUA_ASSERT(L_, lua_gettop(L_) >= _ret);
+    return _ret;
+}
+
+// #################################################################################################
+
+[[nodiscard]]
 std::string_view Lane::pushErrorTraceLevel(lua_State* L_) const
 {
     std::string_view const _str{ errorTraceLevelString() };
@@ -1270,15 +1269,16 @@ int Lane::storeResults(lua_State* const L_)
     lua_getiuservalue(L_, kIdxSelf, UserValueIndex{ 1 });                                          // L_: lane ... {uv}
     StackIndex const _tidx{ lua_gettop(L_) };
 
-    int _stored{};
-    if (nresults == 0) {
+    // if the results were already stored from a previous indexing, just say how many values we have in store
+    if (!L) {
         lua_rawgeti(L_, -1, 0);                                                                    // L_: lane ... {uv} nresults
-        _stored = static_cast<int>(lua_tointeger(L_, -1));
+        auto const _stored{ static_cast<int>(lua_tointeger(L_, -1)) };
         lua_pop(L_, 2);
         STACK_CHECK(L_, 0);
         return _stored;
     }
 
+    int _stored{};
     switch (status.load(std::memory_order_acquire)) {
     default:
         // this is an internal error, we probably never get here
@@ -1358,12 +1358,13 @@ int Lane::storeResults(lua_State* const L_)
 //---
 // str= thread_status( lane )
 //
-// "pending" -> | ("running" <-> "waiting") <-> "suspended" <-> "resuming" | -> "done"/"error"/"cancelled"
+// "pending" -> | ("running" <-> "waiting") <-> "suspended" <-> "resuming/closing" | -> "done"/"error"/"cancelled"
 
 // "pending"   not started yet
 // "running"   started, doing its work..
 // "suspended" returned from a lua_resume
 // "resuming"  told by its parent state to resume
+// "closing"   not observable from the outside: happens only inside a join()/indexation call to unblock a suspended coroutine Lane so that it can join properly
 // "waiting"   blocked in a send()/receive()
 // "done"      finished, results are there
 // "error"     finished at an error, error value is there
@@ -1374,7 +1375,7 @@ std::string_view Lane::threadStatusString() const
 {
     static constexpr std::string_view kStrs[] = {
         "pending",
-        "running", "suspended", "resuming",
+        "running", "suspended", "resuming", "closing",
         "waiting",
         "done", "error", "cancelled"
     };
@@ -1382,12 +1383,13 @@ std::string_view Lane::threadStatusString() const
     static_assert(1 == static_cast<std::underlying_type_t<Lane::Status>>(Running));
     static_assert(2 == static_cast<std::underlying_type_t<Lane::Status>>(Suspended));
     static_assert(3 == static_cast<std::underlying_type_t<Lane::Status>>(Resuming));
-    static_assert(4 == static_cast<std::underlying_type_t<Lane::Status>>(Waiting));
-    static_assert(5 == static_cast<std::underlying_type_t<Lane::Status>>(Done));
-    static_assert(6 == static_cast<std::underlying_type_t<Lane::Status>>(Error));
-    static_assert(7 == static_cast<std::underlying_type_t<Lane::Status>>(Cancelled));
+    static_assert(4 == static_cast<std::underlying_type_t<Lane::Status>>(Closing));
+    static_assert(5 == static_cast<std::underlying_type_t<Lane::Status>>(Waiting));
+    static_assert(6 == static_cast<std::underlying_type_t<Lane::Status>>(Done));
+    static_assert(7 == static_cast<std::underlying_type_t<Lane::Status>>(Error));
+    static_assert(8 == static_cast<std::underlying_type_t<Lane::Status>>(Cancelled));
     auto const _status{ static_cast<std::underlying_type_t<Lane::Status>>(status.load(std::memory_order_acquire)) };
-    if (_status < 0 || _status > 7) { // should never happen, but better safe than sorry
+    if (_status < 0 || _status > 8) { // should never happen, but better safe than sorry
         return "";
     }
     return kStrs[_status];
@@ -1407,3 +1409,40 @@ bool Lane::waitForCompletion(std::chrono::time_point<std::chrono::steady_clock>
         return _status == Lane::Done || _status == Lane::Error || _status == Lane::Cancelled || _status == suspended;
     });
 }
+
+// #################################################################################################
+
+[[nodiscard]]
+bool Lane::waitForJoin(lua_State* const L_, std::chrono::time_point<std::chrono::steady_clock> until_)
+{
+    // wait until suspended or done
+    {
+        bool const _done{ !thread.joinable() || waitForCompletion(until_, true) };
+
+        if (!_done) {
+            lua_pushnil(L_);                                                                       // L_: lane nil
+            luaG_pushstring(L_, "timeout");                                                        // L_: lane nil "timeout"
+            return false;
+        }
+    }
+
+    // if lane is suspended, force the yield loop to break, and the termination of the thread
+    if (status.load(std::memory_order_acquire) == Lane::Suspended) {
+        LUA_ASSERT(L_, waiting_on == &doneCondVar);
+        status.store(Lane::Closing, std::memory_order_release);
+        doneCondVar.notify_all();
+        // wait until done
+        {
+            bool const _done{ !thread.joinable() || waitForCompletion(until_, true) };
+
+            if (!_done) {
+                lua_pushnil(L_);                                                                   // L_: lane nil
+                luaG_pushstring(L_, "timeout");                                                    // L_: lane nil "timeout"
+                return false;
+            }
+        }
+        LUA_ASSERT(L_, status.load(std::memory_order_acquire) != Lane::Closing);
+    }
+    LUA_ASSERT(L_, status.load(std::memory_order_acquire) != Lane::Suspended);
+    return true;
+}
diff --git a/src/lane.hpp b/src/lane.hpp
index fd46d68..bd328b1 100644
--- a/src/lane.hpp
+++ b/src/lane.hpp
@@ -56,6 +56,7 @@ class Lane final
     /*
       Pending: The Lua VM hasn't done anything yet.
       Resuming: The user requested the lane to resume execution from Suspended state.
+      Closing: The user is joining the lane, specifically interrupting a suspended Lane.
       Suspended: returned from lua_resume, waiting for the client to request a lua_resume.
       Running, Suspended, Waiting: Thread is inside the Lua VM.
       Done, Error, Cancelled: Thread execution is outside the Lua VM. It can be lua_close()d.
@@ -66,6 +67,7 @@ class Lane final
         Running,
         Suspended,
         Resuming,
+        Closing,
         Waiting,
         Done,
         Error,
@@ -199,6 +201,8 @@ class Lane final
     static void PushMetatable(lua_State* L_);
     void pushStatusString(lua_State* L_) const;
     void pushIndexedResult(lua_State* L_, int key_) const;
+    [[nodiscard]]
+    int pushStoredResults(lua_State* L_) const;
     void resetResultsStorage(lua_State* L_, StackIndex self_idx_);
     void selfdestructAdd();
     [[nodiscard]]
@@ -213,6 +217,8 @@ class Lane final
     // wait until the lane stops working with its state (either Suspended or Done+)
     [[nodiscard]]
     bool waitForCompletion(std::chrono::time_point<std::chrono::steady_clock> until_, bool const _acceptSuspended);
+    [[nodiscard]]
+    bool waitForJoin(lua_State* _L, std::chrono::time_point<std::chrono::steady_clock> until_);
 };
 
 // #################################################################################################
diff --git a/unit_tests/scripts/coro/collect_yielded_lane.lua b/unit_tests/scripts/coro/collect_yielded_lane.lua
index 0459698..2bc4ae8 100644
--- a/unit_tests/scripts/coro/collect_yielded_lane.lua
+++ b/unit_tests/scripts/coro/collect_yielded_lane.lua
@@ -1,4 +1,5 @@
-local lanes = require "lanes"
+local fixture = require "fixture"
+local lanes = require "lanes".configure{on_state_create = fixture.on_state_create}
 
 local fixture = require "fixture"
 lanes.finally(fixture.throwing_finalizer)
@@ -7,18 +8,27 @@ local utils = lanes.require "_utils"
 local PRINT = utils.MAKE_PRINT()
 
 -- a lane body that yields stuff
-local yielder = function(out_linda_)
+local yielder = function(out_linda_, wait_)
+        local fixture = assert(require "fixture")
         -- here is a to-be-closed variable that, when closed, sends "Closed!" in the "out" slot of the provided linda
         local t <close> = setmetatable(
                 { text = "Closed!" }, {
                         __close = function(self, err)
+                                if wait_ then
+                                        fixture.block_for(wait_)
+                                end
                                 out_linda_:send("out", self.text)
                         end
                 }
         )
-        -- yield forever
+        -- yield forever, but be cancel-friendly
+        local n = 1
         while true do
-                coroutine.yield("I yield!")
+                coroutine.yield("I yield!", n)
+                if cancel_test and cancel_test() then -- cancel_test does not exist when run immediately (not in a Lane)
+                        return "I am cancelled"
+                end
+                n = n + 1
         end
 end
 
@@ -27,8 +37,8 @@ local out_linda = lanes.linda()
 local test_close = function(what_, f_)
         local c = coroutine.create(f_)
         for i = 1, 10 do
-                local t, r = coroutine.resume(c, out_linda) -- returns true + <yielded values>
-                assert(t == true and r == "I yield!", "got " .. tostring(t) .. " " .. tostring(r))
+                local t, r1, r2 = coroutine.resume(c, out_linda) -- returns true + <yielded values>
+                assert(t == true and r1 == "I yield!" and r2 == i, "got " .. tostring(t) .. " " .. tostring(r1) .. " " .. tostring(r2))
                 local s = coroutine.status(c)
                 assert(s == "suspended")
         end
@@ -39,28 +49,64 @@ local test_close = function(what_, f_)
         assert(s == "out" and r == "Closed!", what_ .. " got " .. tostring(s) .. " " .. tostring(r))
 end
 
--- first, try the close mechanism outside of a lane
-test_close("base", yielder)
+---------------------------------------------------------
+-- TEST: first, try the close mechanism outside of a lane
+---------------------------------------------------------
+if true then
+        test_close("base", yielder)
+end
 
--- try again with a function obtained through dump/undump
--- note this means our yielder implementation can't have upvalues, as they are lost in the process
-test_close("dumped", load(string.dump(yielder)))
+---------------------------------------------------------------
+-- TEST: try again with a function obtained through dump/undump
+---------------------------------------------------------------
+if true then
+        -- note this means our yielder implementation can't have upvalues, as they are lost in the process
+        test_close("dumped", load(string.dump(yielder)))
+end
 
 ------------------------------------------------------------------------------
--- TEST: to-be-closed variables are properly closed when the lane is collected
+-- TEST: to-be-closed variables are properly closed whzen the lane is collected
 ------------------------------------------------------------------------------
-if false then -- NOT IMPLEMENTED YET!
-
+if true then
         -- the generator
         local coro_g = lanes.coro("*", yielder)
 
         -- start the lane
         local h = coro_g(out_linda)
 
-        -- join it so that it reaches suspended state
-        local r, v = h:join(0.5)
+        -- join the lane. it should be done and give back the values resulting of the first yield point
+        local r, v1, v2 = h:join()
+        assert(r == true and v1 == "I yield!" and v2 == 1, "got " .. tostring(r) .. " " .. tostring(v1) .. " " .. tostring(v2))
+        assert(h.status == "done", "got " .. h.status)
+
+        -- force collection of the lane
+        h = nil
+        collectgarbage()
+
+        -- I want the to-be-closed variable of the coroutine linda to be properly closed
+        local s, r = out_linda:receive(0, "out")
+        assert(s == "out" and r == "Closed!", "coro got " .. tostring(s) .. " " .. tostring(r)) -- THIS TEST FAILS
+end
+
+---------------------------------------------------------------------------------------------------
+-- TEST: if a to-be-closed handler takes longer than the join timeout, everything works as expected
+---------------------------------------------------------------------------------------------------
+if true then
+        -- the generator
+        local coro_g = lanes.coro("*", yielder)
+
+        -- start the lane. The to-be-closed handler will sleep for 1 second
+        local h = coro_g(out_linda, 1)
+
+        -- first join attempt should timeout
+        local r, v = h:join(0.6)
         assert(r == nil and v == "timeout", "got " .. tostring(r) .. " " .. tostring(v))
-        assert(h.status == "suspended")
+        assert(h.status == "running", "got " .. h.status)
+
+        -- join the lane again. it should be done and give back the values resulting of the first yield point
+        local r, v1, v2 = h:join(0.6)
+        assert(r == true and v1 == "I yield!" and v2 == 1, "got " .. tostring(r) .. " " .. tostring(v1) .. " " .. tostring(v2))
+        assert(h.status == "done", "got " .. h.status)
 
         -- force collection of the lane
         h = nil
@@ -68,5 +114,28 @@ if false then -- NOT IMPLEMENTED YET!
 
         -- I want the to-be-closed variable of the coroutine linda to be properly closed
         local s, r = out_linda:receive(0, "out")
-        assert(s == "out" and r == "Closed!", "coro got " .. tostring(s) .. " " .. tostring(r))
+        assert(s == "out" and r == "Closed!", "coro got " .. tostring(s) .. " " .. tostring(r)) -- THIS TEST FAILS
+end
+
+--------------------------------------------------
+-- TEST: cancelling a suspended Lane should end it
+--------------------------------------------------
+if true then
+        -- the generator
+        local coro_g = lanes.coro("*", yielder)
+
+        -- start the lane
+        local h = coro_g(out_linda)
+        repeat until h.status == "suspended"
+
+        -- first cancellation attempt: don't wake the lane
+        local b, r = h:cancel("soft", 0.5)
+        -- the lane is still blocked in its suspended state
+        assert(b == false and r == "timeout" and h.status == "suspended", "got " .. tostring(b) .. " " .. tostring(r) .. " " .. h.status)
+
+        -- cancel the Lane again, this time waking it. it will resume, and yielder()'s will break out of its infinite loop
+        h:cancel("soft", nil, true)
+
+        -- lane should be done, because it returned cooperatively when detecting a soft cancel
+        assert(h.status == "done", "got " .. h.status)
 end
diff --git a/unit_tests/scripts/coro/yielding_function.lua b/unit_tests/scripts/coro/yielding_function.lua
index 636f094..6518d1f 100644
--- a/unit_tests/scripts/coro/yielding_function.lua
+++ b/unit_tests/scripts/coro/yielding_function.lua
@@ -23,7 +23,7 @@ end
 --------------------------------------------------------------------------------------------------
 -- TEST: if we start a non-coroutine lane with a yielding function, we should get an error, right?
 --------------------------------------------------------------------------------------------------
-if false then
+if true then
     local fun_g = lanes.gen("*", { name = 'auto' }, yielder)
     local h = fun_g("hello", "world", "!")
     local err, status, stack = h:join()
@@ -48,7 +48,7 @@ local coro_g = lanes.coro("*", {name = "auto"}, yielder)
 -------------------------------------------------------------------------------------------------
 -- TEST: we can resume as many times as the lane yields, then read the returned value on indexing
 -------------------------------------------------------------------------------------------------
-if false then
+if true then
     -- launch coroutine lane
     local h = coro_g("hello", "world", "!")
     -- read the yielded values, sending back the expected index
@@ -63,7 +63,7 @@ end
 ---------------------------------------------------------------------------------------------
 -- TEST: we can resume as many times as the lane yields, then read the returned value on join
 ---------------------------------------------------------------------------------------------
-if false then
+if true then
     -- launch coroutine lane
     local h = coro_g("hello", "world", "!")
     -- read the yielded values, sending back the expected index
@@ -75,9 +75,9 @@ if false then
     assert(h.status == "done" and s == true and r == "bye!")
 end
 
----------------------------------------------------------------------------------------------------
--- TEST: if we join a yielded lane, we get a timeout, and we can resume as if we didn't try to join
----------------------------------------------------------------------------------------------------
+---------------------------------------------------
+-- TEST: if we join a yielded lane, the lane aborts
+---------------------------------------------------
 if true then
     -- launch coroutine lane
     local h = coro_g("hello", "world", "!")
@@ -89,10 +89,10 @@ if true then
     assert(s == "done" and b == true and r == "world", "got " .. s .. " " .. tostring(b) .. " " .. tostring(r))
 end
 
------------------------------------------------------------------------
--- TEST: if we index yielded lane, we should get the last yielded value
------------------------------------------------------------------------
-if false then
+-------------------------------------------------------------------------
+-- TEST: if we index a yielded lane, we should get the last yielded value
+-------------------------------------------------------------------------
+if true then
     -- launch coroutine lane
     local h = coro_g("hello", "world", "!")
     -- read the first yielded value, sending back the expected index
@@ -102,15 +102,7 @@ if false then
     local r2 = h[1]
     local r3 = h[1]
     assert(r1 == "world" and r2 == "world" and r3 == "world", "got " .. r1 .. " " .. r2 .. " " .. r3)
-    assert(h:resume(2) == "world")
-
-    -- THERE IS AN INCONSISTENCY: h:resume pulls the yielded values directly out of the lane's stack
-    -- but h[n] removes them and stores them in the internal values storage table
-    -- TODO: so we need to decide: should indexing a yielded lane work like resume()?
-    assert(h:resume(3) == "!")
+    -- once the lane was indexed, it is no longer resumable (just like after join)
+    local b, e = pcall(h.resume, h, 2)
+    assert(b == false and e == "cannot resume non-suspended coroutine Lane")
 end
-
--------------------------------------------------------------------------------------
--- TEST: if we close yielded lane, we can join it and get the last yielded values out
--------------------------------------------------------------------------------------
--- TODO: we need to implement lane:close() for that!