8 files changed, 43 insertions, 20 deletions

diff --git a/docs/index.html b/docs/index.html
index 3dc2b61..11ed3eb 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -65,13 +65,13 @@
                 <font size="-1">
                         <p>
                                 <br />
-                                <i>Copyright &copy; 2007-25 Asko Kauppi, Benoit Germain. All rights reserved.</i>
+                                <i>Copyright &copy; 2007-26 Asko Kauppi, Benoit Germain. All rights reserved.</i>
                                 <br />
                                 Lua Lanes is published under the same <a href="http://en.wikipedia.org/wiki/MIT_License">MIT license</a> as Lua 5.1, 5.2, 5.3, 5.4 and 5.5.
                         </p>
 
                         <p>
-                                This document was revised on 29-Sep-2025, and applies to version <tt>4.0.0</tt>.
+                                This document was revised on 26-Feb-2026, and applies to version <tt>4.0.0</tt>.
                         </p>
                 </font>
         </center>
@@ -1200,7 +1200,7 @@
                                 <li><tt>"extended"</tt>: <tt>stack_tbl</tt> is an array of tables containing info gathered with <tt>lua_getinfo()</tt> (<tt>"source"</tt>,<tt>"currentline"</tt>,<tt>"name"</tt>,<tt>"namewhat"</tt>,<tt>"what"</tt>).</li>
                         </ul>
                 </li>
-                <li><tt>nil, "killed"</tt> if forcefully killed.</li>
+                <li><tt>nil, lanes.cancel_error</tt> if <tt>"hard"</tt>-cancelled during a <a href="#lindas">linda</a> operation (which is nothing more than a special case of the above).</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>.
@@ -1262,14 +1262,14 @@
                 <li>
                         <tt>"hard"</tt>: waits for the request to be processed, or a timeout to occur. <a href="#lindas">linda</a> operations detecting the cancellation request will raise a special cancellation error (meaning they won't return in that case).
                         <br />
-                        If the lane isn't actually waiting on a <a href="#lindas">linda</a> when the request is issued, a lane calling <tt>cancel_test()</tt> will see it return <tt>"hard"</tt>.
+                        If the lane isn't actually waiting on a <a href="#lindas">linda</a> when the request is issued, a lane calling <tt>cancel_test()</tt> will also raise <tt>lanes.cancel_error</tt>, unless <tt>cancel_test(true)</tt> is used, in which case it returns <tt>"hard"</tt> instead.
                         <br />
-                        <tt>wake_lane</tt> defaults to <tt>true</tt>, and <tt>timeout</tt> defaults to 0 if not specified.
+                        <tt>wake_lane</tt> defaults to <tt>true</tt>, and <tt>timeout</tt> defaults to infinite if not specified.
                 </li>
                 <li>
                         <tt>"call"</tt>, <tt>"ret"</tt>, <tt>"line"</tt>, <tt>"count"</tt>: Asynchronously install the corresponding hook, then behave as <tt>"hard"</tt>.
                         <br />
-                        If the lane has the opportunity to call <tt>cancel_test()</tt> before the hook is invoked, calling <tt>cancel_test()</tt> will see it return <tt>"hard"</tt>.
+                        If the lane has the opportunity to call <tt>cancel_test()</tt> before the hook is invoked, it will also raise <tt>lanes.cancel_error</tt> (or return <tt>"hard"</tt> if <tt>cancel_test(true)</tt> is used).
                 </li>
                 <li>
                         <tt>"all"</tt>: Installs all hooks in one shot, just to be sure.
@@ -1297,10 +1297,15 @@
 </p>
 
         <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
-        false|"soft"|"hard" = cancel_test() -- inside the lane
+        false|"soft" = cancel_test()        -- raises cancel_error on hard cancel
+        false|"soft"|"hard" = cancel_test(true) -- returns "hard" instead of raising
 </pre></td></tr></table>
 <p>
         Lanes installs the function <tt>cancel_test()</tt> in each created lane to manually test for cancel requests.
+        It returns <tt>false</tt> when no cancel is pending, <tt>"soft"</tt> on a soft cancel request, and raises
+        <tt>lanes.cancel_error</tt> on a hard cancel request. Passing <tt>true</tt> as the optional argument suppresses
+        the raise and returns <tt>"hard"</tt> instead, which is useful when the lane needs to distinguish the cancel
+        mode before deciding how to react.
 </p>
 
 <!-- finalizers +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
diff --git a/src/cancel.cpp b/src/cancel.cpp
index 6812b0d..245065d 100644
--- a/src/cancel.cpp
+++ b/src/cancel.cpp
@@ -112,18 +112,28 @@ CancelRequest CheckCancelRequest(lua_State* const L_)
 // #################################################################################################
 
 //---
-// bool = cancel_test()
+// false|"soft" = cancel_test([return_hard])
 //
-// Available inside the global namespace of a lane
-// returns a boolean saying if a cancel request is pending
+// Available inside the global namespace of a lane.
+// Returns false when no cancel request is pending.
+// Returns "soft" when a soft cancel request is pending.
+// Raises cancel_error when a hard cancel request is pending,
+// unless the optional boolean argument is true, in which case it returns "hard" instead.
 //
 LUAG_FUNC(cancel_test)
 {
     CancelRequest const _test{ CheckCancelRequest(L_) };
     if (_test == CancelRequest::None) {
         lua_pushboolean(L_, 0);
+    } else if (_test == CancelRequest::Soft) {
+        luaW_pushstring(L_, "soft");
     } else {
-        luaW_pushstring(L_, (_test == CancelRequest::Soft) ? "soft" : "hard");
+        // Hard cancel: raise by default, return "hard" if the optional argument is true
+        if (lua_toboolean(L_, 1)) {
+            luaW_pushstring(L_, "hard");
+        } else {
+            raise_cancel_error(L_); // doesn't return
+        }
     }
     return 1;
 }
diff --git a/tests/atexit.lua b/tests/atexit.lua
index ba10d3b..744b705 100644
--- a/tests/atexit.lua
+++ b/tests/atexit.lua
@@ -11,7 +11,7 @@ end
 local g = function()
         local cancelled
         repeat
-                cancelled = cancel_test()
+                cancelled = cancel_test(true)
         until cancelled
         print "User cancellation detected!"
 end
diff --git a/tests/cancel.lua b/tests/cancel.lua
index 66957c3..c5ff0e6 100644
--- a/tests/cancel.lua
+++ b/tests/cancel.lua
@@ -130,7 +130,7 @@ local laneBody = function(mode_, payload_)
                 else
                         error "no mode: raise an error"
                 end
-        until cancel_test() -- soft cancel self test
+        until cancel_test(true) -- soft cancel self test
         print "                 lane shutting down after breaking out of loop"
 end
 
diff --git a/unit_tests/scripts/_utils.lua b/unit_tests/scripts/_utils.lua
index 9f46237..365fd10 100644
--- a/unit_tests/scripts/_utils.lua
+++ b/unit_tests/scripts/_utils.lua
@@ -76,7 +76,7 @@ local yield_one_by_one = function(...)
         local _val = select(_i, ...)
         PRINT("yielding #", _i, _val)
         local _ack = coroutine.yield(_val)
-        if cancel_test and cancel_test() then -- cancel_test does not exist when run immediately (not in a Lane)
+        if cancel_test and cancel_test(true) then -- cancel_test does not exist when run immediately (not in a Lane)
             return "cancelled!"
         end
         -- of course, if we are cancelled, we were not resumed, and yield() didn't return what we expect
diff --git a/unit_tests/scripts/_utils54.lua b/unit_tests/scripts/_utils54.lua
index a511563..629f5c5 100644
--- a/unit_tests/scripts/_utils54.lua
+++ b/unit_tests/scripts/_utils54.lua
@@ -20,7 +20,7 @@ utils.yielder_with_to_be_closed = function(out_linda_, wait_)
         local n = 1
         while true do
                 coroutine.yield("I yield!", n)
-                if cancel_test and cancel_test() then -- cancel_test does not exist when run immediately (not in a Lane)
+                if cancel_test and cancel_test(true) then -- cancel_test does not exist when run immediately (not in a Lane)
                         return "I am cancelled"
                 end
                 n = n + 1
diff --git a/unit_tests/scripts/lane/cooperative_shutdown.lua b/unit_tests/scripts/lane/cooperative_shutdown.lua
index 0a0943e..3329e9d 100644
--- a/unit_tests/scripts/lane/cooperative_shutdown.lua
+++ b/unit_tests/scripts/lane/cooperative_shutdown.lua
@@ -7,7 +7,7 @@ local lane1 = function()
         -- loop breaks on soft cancellation request
         repeat
                 lanes.sleep(0)
-        until cancel_test()
+        until cancel_test(true)
         print "lane1 cancelled"
 end
 
diff --git a/unit_tests/scripts/lane/tasking_cancelling.lua b/unit_tests/scripts/lane/tasking_cancelling.lua
index 395bee5..f7ad729 100644
--- a/unit_tests/scripts/lane/tasking_cancelling.lua
+++ b/unit_tests/scripts/lane/tasking_cancelling.lua
@@ -29,24 +29,32 @@ local no_cancel_result = no_cancel_lane[1]
 assert(no_cancel_result == false, "cancel_test() should return boolean false, got " .. type(no_cancel_result) .. ": " .. tostring(no_cancel_result))
 
 -- cancellation of cooperating lanes
-local cooperative = function()
+-- query_only: if true, pass true to cancel_test() so that hard cancel returns "hard" instead of raising
+local cooperative = function(query_only_)
     local fixture = assert(require "fixture")
     local which_cancel
     repeat
         fixture.block_for(0.2)
-        which_cancel = cancel_test()
+        which_cancel = cancel_test(query_only_)
     until which_cancel
     return which_cancel
 end
--- soft and hard are behaviorally equivalent when no blocking linda operation is involved
+-- for soft cancel, cancel_test() returns "soft" so the lane exits the loop and returns it
 local cooperative_lane_soft = lanes_gen("*", { name = 'auto' }, cooperative)()
 local a, b = cooperative_lane_soft:cancel("soft", 0) -- issue request, do not wait for lane to terminate
 assert(a == false and b == "timeout", "got " .. tostring(a) .. " " .. tostring(b))
 assert(cooperative_lane_soft[1] == "soft", "cancel_test() should return \"soft\", got " .. type(cooperative_lane_soft[1]) .. ": " .. tostring(cooperative_lane_soft[1])) -- return value of the lane body is the value returned by cancel_test()
+-- for hard cancel, cancel_test() raises cancel_error, so the lane ends up in the cancelled state
 local cooperative_lane_hard = lanes_gen("*", { name = 'auto' }, cooperative)()
 local c, d = cooperative_lane_hard:cancel("hard", 0) -- issue request, do not wait for lane to terminate
 assert(c == false and d == "timeout", "got " .. tostring(c) .. " " .. tostring(d))
-assert(cooperative_lane_hard[1] == "hard", "cancel_test() should return \"hard\", got " .. type(cooperative_lane_hard[1]) .. ": " .. tostring(cooperative_lane_hard[1])) -- return value of the lane body is the value returned by cancel_test()
+assert(cooperative_lane_hard[1] == nil, "cancelled lane first result should be nil, got " .. type(cooperative_lane_hard[1]) .. ": " .. tostring(cooperative_lane_hard[1]))
+assert(cooperative_lane_hard[2] == lanes.cancel_error, "cancelled lane second result should be cancel_error")
+-- for hard cancel with query_only=true, cancel_test(true) returns "hard" so the lane exits the loop and returns it
+local cooperative_lane_hard_query = lanes_gen("*", { name = 'auto' }, cooperative)(true)
+local e, f = cooperative_lane_hard_query:cancel("hard", 0) -- issue request, do not wait for lane to terminate
+assert(e == false and f == "timeout", "got " .. tostring(e) .. " " .. tostring(f))
+assert(cooperative_lane_hard_query[1] == "hard", "cancel_test(true) should return \"hard\", got " .. type(cooperative_lane_hard_query[1]) .. ": " .. tostring(cooperative_lane_hard_query[1]))
 
 -- ##################################################################################################