From efb81b501adbbddf25615bbcc216bbbf3a3c8e0a Mon Sep 17 00:00:00 2001
From: Benoit Germain <benoit.germain@ubisoft.com>
Date: Wed, 23 Apr 2025 14:27:00 +0200
Subject: cancel_test() returns "soft"/"hard" instead of true

---
 CHANGES                                          |  1 +
 docs/index.html                                  | 23 +++++++++++++++++------
 src/cancel.cpp                                   |  6 +++++-
 unit_tests/scripts/lane/cooperative_shutdown.lua |  1 -
 4 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/CHANGES b/CHANGES
index ccfa923..4dc9d2d 100644
--- a/CHANGES
+++ b/CHANGES
@@ -38,6 +38,7 @@ CHANGE 2: BGe 27-Nov-24
                 - 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:get_debug_threadname() renamed get_threadname().
+            - 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 e3e8c7a..e3fbd0b 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -71,7 +71,7 @@
 			</p>
 
 			<p>
-				This document was revised on 21-Apr-25, and applies to version <tt>4.0.0</tt>.
+				This document was revised on 23-Apr-25, and applies to version <tt>4.0.0</tt>.
 			</p>
 		</font>
 	</center>
@@ -215,6 +215,7 @@
 	<li>
 		Inside the lane
 		<ul>
+			<li><tt>cancel_test()</tt>: check for cancellation requests</li>
 			<li><tt>lane_threadname()</tt>: read or change the name of the thread</li>
 			<li><tt>set_finalizer()</tt>: install a function called when the lane exits</li>
 		</ul>
@@ -1222,26 +1223,36 @@
 	First argument is a <tt>mode</tt>. It can be one of:
 	<ul>
 		<li>
-			<tt>"soft"</tt>: Cancellation will only cause <tt>cancel_test()</tt> to return <tt>true</tt>, so that the lane can cleanup manually.
+			<tt>"soft"</tt>: Cancellation will only cause <tt>cancel_test()</tt> to return <tt>"soft"</tt>, so that the lane can cleanup manually.
 			<br />
 			Lindas will also check for cancellation inside blocking calls to early out based on their <tt>wake_period</tt>.
 		</li>
 		<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 />
+			<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 Linda when the request is issued, a lane calling <tt>cancel_test()</tt> will see it return <tt>"hard"</tt>.
+			<br />
 			<tt>wake_lane</tt> defaults to <tt>true</tt>, and <tt>timeout</tt> defaults to 0 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>.
 		</li>
 		<li>
 			<tt>"all"</tt>: Installs all hooks in one shot, just to be sure.
 		</li>
 	</ul>
-	If <tt>mode</tt> is not specified, it defaults to <tt>"hard"</tt>.
+	<p>
+		If <tt>mode</tt> is not specified, it defaults to <tt>"hard"</tt>.
+	</p>
+</p>
+<p>
 	If <tt>wake_lane</tt> is <tt>true</tt>, the lane is also signalled so that execution returns from any pending <a href="#lindas">linda</a> operation. <a href="#lindas">linda</a> operations detecting the cancellation request return <tt>lanes.cancel_error</tt>.
 </p>
-<tt>timeout</tt> is an optional number &gt= 0. Defaults to infinite if left unspecified or <tt>nil</tt>.
-<br />
+<p>
+	<tt>timeout</tt> is an optional number &gt= 0. Defaults to infinite if left unspecified or <tt>nil</tt>.
+</p>
 <p>
 	If the lane is still running after the timeout expired, there is a chance lanes will freeze forever at shutdown when failing to terminate all free-running lanes within the specified timeout.
 </p>
diff --git a/src/cancel.cpp b/src/cancel.cpp
index 5bba9fc..ec9b6e4 100644
--- a/src/cancel.cpp
+++ b/src/cancel.cpp
@@ -133,7 +133,11 @@ static CancelOp WhichCancelOp(lua_State* const L_, StackIndex const idx_)
 LUAG_FUNC(cancel_test)
 {
     CancelRequest const _test{ CheckCancelRequest(L_) };
-    lua_pushboolean(L_, _test != CancelRequest::None);
+    if (_test == CancelRequest::None) {
+        lua_pushboolean(L_, 0);
+    } else {
+        luaG_pushstring(L_, (_test == CancelRequest::Soft) ? "soft" : "hard");
+    }
     return 1;
 }
 
diff --git a/unit_tests/scripts/lane/cooperative_shutdown.lua b/unit_tests/scripts/lane/cooperative_shutdown.lua
index 756e33c..0e30f91 100644
--- a/unit_tests/scripts/lane/cooperative_shutdown.lua
+++ b/unit_tests/scripts/lane/cooperative_shutdown.lua
@@ -23,7 +23,6 @@ end
 local lane3 = function()
 	lane_threadname("lane3")
 	-- this one cooperates too, because of the hook cancellation modes that Lanes will be using
-	-- but not with LuaJIT, because the function is compiled, and we don't call anyone, so no hook triggers
 	local fixture = require "fixture"
 	repeat until fixture.give_me_back(false)
 end
-- 
cgit v1.2.3-55-g6feb