Unify sleep() timeout with send() and receive (nil means forever)v4.0.0

5 files changed, 28 insertions, 28 deletions

diff --git a/CHANGES b/CHANGES
index 4324035..fd45f10 100644
--- a/CHANGES
+++ b/CHANGES
@@ -12,7 +12,7 @@ CHANGE 2: BGe 26-Feb-26
         - Lanes module:
             - shared library is now lanes_core.[so|dll] instead of lanes/core.[so|dll]
             - lanes.register() is also available as lanes_register() in the exported C API.
-            - lanes.sleep() accepts a new argument "indefinitely" to block forever (until hard cancellation is received).
+            - lanes.sleep(): passing nil or no argument now blocks indefinitely (until cancellation is received).
             - function set_debug_threadname() available inside a Lane is renamed lane_threadname(); can now both read and write the name.
             - function cancel_test() raises cancel_error by default in a hard-cancelled lane.
             - new function lanes.finally(). Installs a function that gets called at Lanes shutdown after attempting to terminate all lanes.
diff --git a/docs/index.html b/docs/index.html
index c9a85ac..a36119e 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -218,7 +218,7 @@
         <li>
                 Inside the lane
                 <ul>
-                        <li><tt>cancel_test()</tt>: check for cancellation requests</li>
+                        <li><tt>cancel_test()</tt>: check for <a href="#cancelling">cancellation</a> 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>
@@ -226,7 +226,7 @@
         <li>
                 Given some <a href="#lindas">linda</a> <tt>l</tt>
                 <ul>
-                        <li><tt>l:cancel()</tt>: mark a <a href="#lindas">linda</a> for cancellation</li>
+                        <li><tt>l:cancel()</tt>: mark a <a href="#lindas">linda</a> for <a href="#cancelling">cancellation</a></li>
                         <li><tt>l:collectgarbage()</tt>: trigger a GC cycle in the <a href="#lindas">linda</a>'s Keeper state</li>
                         <li><tt>l:deep()</tt>: obtain a light userdata uniquely representing the <a href="#lindas">linda</a></li>
                         <li><tt>l:dump()</tt>: have information about slot contents</li>
@@ -452,8 +452,8 @@
                                 Sets the default period in seconds a <a href="#lindas">linda</a> will wake by itself during blocked operations. Default is never.<br />
                                 When a <a href="#lindas">linda</a> enters a blocking call (<tt>send()</tt>, <tt>receive()</tt>, <tt>receive_batched()</tt>, <tt>sleep()</tt>), it normally sleeps either until the operation completes
                                 or the specified timeout expires. With this setting, the default behavior can be changed to wake periodically. This can help for example with timing issues where a lane is signalled
-                                for cancellation, but a <a href="#lindas">linda</a> inside the lane was in the middle of processing an operation but did not actually start the wait. This can result in the signal to be ignored, thus
-                                causing the <a href="#lindas">linda</a> to wait out the full operation timeout before cancellation is processed.
+                                for <a href="#cancelling">cancellation</a>, but a <a href="#lindas">linda</a> inside the lane was in the middle of processing an operation but did not actually start the wait. This can result in the signal to be ignored, thus
+                                causing the <a href="#lindas">linda</a> to wait out the full operation timeout before <a href="#cancelling">cancellation</a> is processed.
                         </td>
                 </tr>
 
@@ -499,7 +499,7 @@
                         </td>
                         <td>
                                 Sets the duration in seconds Lanes will wait for graceful termination of running lanes at application shutdown. Default is <tt>0.25</tt>.<br />
-                                Lanes signals all lanes for cancellation with <tt>"soft"</tt>, <tt>"hard"</tt>, and <tt>"all"</tt> modes, in that order. Each attempt has <tt>shutdown_timeout</tt> seconds to succeed before the next one.<br />
+                                Lanes signals all lanes for <a href="#cancelling">cancellation</a> with <tt>"soft"</tt>, <tt>"hard"</tt>, and <tt>"all"</tt> modes, in that order. Each attempt has <tt>shutdown_timeout</tt> seconds to succeed before the next one.<br />
                                 Then there is a last chance at cleanup with <a href="#finally"><tt>lanes.finally()</tt></a>. If some lanes are still running after that point, shutdown will either freeze or throw. It is YOUR responsibility to cleanup properly after yourself.
                                 IMPORTANT: If there are still running lanes at shutdown, an error is raised, which will be propagated by Lua to the handler installed by <tt>lua_setwarnf</tt>. If the finalizer returned a value, this will be used as the error message.<br />
                                 LANES SHUTDOWN WILL NOT BE COMPLETE IN THAT CASE, AND THE SUBSEQUENT CONSEQUENCES ARE UNDEFINED!
@@ -1561,7 +1561,7 @@
 <p>
         <tt>get()</tt> can read several values at once, and does not block. Return values ares:
         <ul>
-                <li><tt>nil, lanes.cancel_error</tt> in case of cancellation.</li>
+                <li><tt>nil, lanes.cancel_error</tt> in case of <a href="#cancelling">cancellation</a>.</li>
                 <li><tt>number, val...</tt> where number is the actual count of items obtained from the linda (can be 0).</li>
         </ul>
 </p>
@@ -1768,12 +1768,12 @@
 </p>
 
 <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
-        nil, "timeout" = lanes.sleep(['indefinitely'|seconds|nil])
+        nil, "timeout" = lanes.sleep([seconds|nil])
 </pre></td></tr></table>
 
 <p>
         A very simple way of sleeping when nothing else is available. Is implemented by attempting to read some data in an unused channel of the internal <a href="#lindas">linda</a> used for timers (this <a href="#lindas">linda</a> exists even when timers aren't enabled).
-        Default duration is 0, which should only cause a thread context switch.<br />
+        Passing <tt>nil</tt> or no argument sleeps indefinitely (until <a href="#cancelling">cancellation</a> is received). Passing a non-negative number sleeps for that many seconds.<br />
         Return values should always be <tt>nil, "timeout"</tt> (or <tt>nil, lanes.cancel_error</tt> in case of interruption).
 </p>
 
@@ -2138,13 +2138,13 @@ static MyDeepFactory g_MyDeepFactory;
 <h3 id="cancelling_cancel">Cancelling cancel</h3>
 
 <p>
-        Cancellation of lanes uses the Lua error mechanism with a special lightuserdata error sentinel.
+        <a href="#cancelling">Cancellation</a> of lanes uses the Lua error mechanism with a special lightuserdata error sentinel.
         If you use <tt>pcall</tt> in code that needs to be cancellable from the outside, the special error might not get through to Lanes, thus preventing the lane from being cleanly cancelled.
         You should throw any lightuserdata error further.
 </p>
 
 <p>
-        This system can actually be used by application to detect cancel, do your own cancellation duties, and pass on the error so Lanes will get it. If it does not get a clean cancellation from a lane in due time, it may forcefully kill the lane.
+        This system can actually be used by application to detect cancel, do your own <a href="#cancelling">cancellation</a> duties, and pass on the error so Lanes will get it. If it does not get a clean cancellation from a lane in due time, it may forcefully kill the lane.
 </p>
 
 <p>
diff --git a/src/lanes.cpp b/src/lanes.cpp
index ef8577b..cf227f9 100644
--- a/src/lanes.cpp
+++ b/src/lanes.cpp
@@ -169,25 +169,23 @@ LUAG_FUNC(sleep)
     extern LUAG_FUNC(linda_receive);
 
     Universe* const _U{ Universe::Get(L_) };
-    lua_settop(L_, 1);
-    lua_pushcfunction(L_, LG_linda_receive);                                                       // L_: duration|nil receive()
+    lua_settop(L_, 1);                                                                             // L_: duration?
+    lua_pushcfunction(L_, LG_linda_receive);                                                       // L_: duration? receive()
     STACK_CHECK_START_REL(L_, 0); // we pushed the function we intend to call, now prepare the arguments
-    _U->timerLinda->push(L_);                                                                      // L_: duration|nil receive() timerLinda
-    if (luaW_tostring(L_, StackIndex{ 1 }) == "indefinitely") {
-        lua_pushnil(L_);                                                                           // L_: duration? receive() timerLinda nil
-    } else if (lua_isnoneornil(L_, 1)) {
-        lua_pushnumber(L_, 0);                                                                     // L_: duration? receive() timerLinda 0
-    } else if (!lua_isnumber(L_, 1)) {
-        raise_luaL_argerror(L_, StackIndex{ 1 }, "duration must be a number");
-    }
-    else {
+    _U->timerLinda->push(L_);                                                                      // L_: duration? receive() timerLinda
+    if (lua_isnumber(L_, 1)) {
         auto const _n{ lua_tonumber(L_, 1) };
         if (_n < 0) {
             raise_luaL_argerror(L_, StackIndex{ 1 }, "duration must be >= 0");
         }
-        lua_pushnumber(L_, lua_tonumber(L_, 1));                                                   // L_: duration? receive() timerLinda duration
+        lua_pushvalue(L_, StackIndex{ 1 });                                                        // L_: duration? receive() timerLinda timeout
+    } else if (lua_isnoneornil(L_, 1)) {
+        lua_pushnil(L_);                                                                           // L_: duration? receive() timerLinda timeout
+    } else {
+        raise_luaL_argerror(L_, StackIndex{ 1 }, "duration must be a number");
     }
-    luaW_pushstring(L_, "ac100de1-a696-4619-b2f0-a26de9d58ab8");                                   // L_: duration? receive() timerLinda duration key
+
+    luaW_pushstring(L_, "ac100de1-a696-4619-b2f0-a26de9d58ab8");                                   // L_: duration? receive() timerLinda timeout key
     STACK_CHECK(L_, 3); // 3 arguments ready
     lua_call(L_, 3, LUA_MULTRET); // timerLinda:receive(duration,key)                              // L_: duration? result...
     return lua_gettop(L_) - 1;
diff --git a/tests/track_lanes.lua b/tests/track_lanes.lua
index ef2ca06..27d5cf4 100644
--- a/tests/track_lanes.lua
+++ b/tests/track_lanes.lua
@@ -46,7 +46,7 @@ end
 local g = lanes.gen( "*", { name = 'auto' }, sleeper)
 
 -- start a forever-waiting lane (nil timeout)
-local forever = g( "forever", 'indefinitely')
+local forever = g( "forever", nil)
 
 -- start a lane that will last 2 seconds
 local ephemeral1 = g( "two_seconds", 2)
diff --git a/unit_tests/lane_tests.cpp b/unit_tests/lane_tests.cpp
index b6fb188..7c215fa 100644
--- a/unit_tests/lane_tests.cpp
+++ b/unit_tests/lane_tests.cpp
@@ -128,9 +128,11 @@ TEST_CASE("lanes.sleep.argument_validation/numbers")
     // negative durations are not supported
     S.requireFailure("lanes.sleep(-1)");
 
-    // no duration is supported (same as 0)
-    S.requireSuccess("lanes.sleep()");
+    // no duration is supported
     S.requireSuccess("lanes.sleep(0)");
+
+    // positive durations are supported
+    S.requireSuccess("lanes.sleep(0.1)");
 }
 
 // #################################################################################################
@@ -161,7 +163,7 @@ TEST_CASE("lanes.sleep.interactions with timers")
         " lanes.timer(l, 'gluh', 0.1, 0.1)"
         // launch a lane that is supposed to sleep forever
         " local g = lanes.gen('*', { name = 'auto' }, lanes.sleep)"
-        " local h = g('indefinitely')"
+        " local h = g(nil)"
         // sleep 1 second (this uses the timer linda)
         " lanes.sleep(1)"
         // shutdown should be able to cancel the lane and stop it instantly