From ebb0837588336e32fc1258a3838673afdd31ee71 Mon Sep 17 00:00:00 2001
From: Benoit Germain <benoit.germain@ubisoft.com>
Date: Tue, 7 May 2024 09:23:12 +0200
Subject: API changes

* lanes.sleep accepts 'indefinitely'.
* settings.with_timers is false by default
---
 docs/index.html       |  6 +++---
 src/lanes.lua         |  6 ++++--
 tests/track_lanes.lua | 50 +++++++++++++++++++++++++++++---------------------
 3 files changed, 36 insertions(+), 26 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index f08947e..e811074 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -311,7 +311,7 @@
 			</td>
 			<td>
 				If equal to <tt>false</tt> or <tt>nil</tt>, Lanes doesn't start the timer service, and the associated API will be absent from the interface (see below).
-				Default is <tt>true</tt>.
+				Default is <tt>false</tt>.
 			</td>
 		</tr>
 
@@ -1328,7 +1328,7 @@ events to a common Linda, but... :).</font>
 </pre></td></tr></table>
 
 <p>
-	Timers are implemented as a lane. They can be disabled by setting "<tt><a href="#with_timers">with_timers</a></tt>" to <tt>nil</tt> or <tt>false</tt> to <tt>lanes.configure()</tt>.
+	Timers are implemented as a lane. They can be enabled by setting "<tt><a href="#with_timers">with_timers</a></tt>" to <tt>true</tt> in <tt>lanes.configure()</tt> settings.
 </p>
 
 <p>
@@ -1395,7 +1395,7 @@ events to a common Linda, but... :).</font>
 </p>
 
 <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
-	void = lanes.sleep([seconds|false])
+	void = lanes.sleep(['indefinitely'|seconds|false])
 </pre></td></tr></table>
 
 <p>
diff --git a/src/lanes.lua b/src/lanes.lua
index f95dddf..caa8818 100644
--- a/src/lanes.lua
+++ b/src/lanes.lua
@@ -71,7 +71,7 @@ local default_params =
     on_state_create = nil,
     shutdown_timeout = 0.25,
     shutdown_mode = "hard",
-    with_timers = true,
+    with_timers = false,
     track_lanes = false,
     demote_full_userdata = nil,
     verbose_errors = false,
@@ -626,7 +626,9 @@ end
 -- PUBLIC LANES API
 local sleep = function(seconds_)
     seconds_ = seconds_ or 0.0 -- this causes false and nil to be a valid input, equivalent to 0.0, but that's ok
-    if type(seconds_) ~= "number" then
+    if seconds_ == 'indefinitely' then
+        seconds_ = nil
+    elseif type(seconds_) ~= "number" then
         error("invalid duration " .. string_format("%q", tostring(seconds_)))
     end
     -- receive data on a channel no-one ever sends anything, thus blocking for the specified duration
diff --git a/tests/track_lanes.lua b/tests/track_lanes.lua
index 46cfdad..daaa94c 100644
--- a/tests/track_lanes.lua
+++ b/tests/track_lanes.lua
@@ -1,22 +1,20 @@
 local lanes = require "lanes" .configure{ with_timers = false, track_lanes = true}
-
-local wait
-do
-    local linda = lanes.linda()
-    wait = function( seconds_)
-        linda:receive( seconds_, "dummy_key")
-    end
-end
+local wait = lanes.sleep
 
 print "hello"
 
-local track = function( title_)
+local track = function( title_, expected_count_)
     print( title_)
-    for k, v in pairs( lanes.threads())
+    local count = 0
+    local threads = lanes.threads()
+    for k, v in pairs(threads)
     do
         print( k, v.name, v.status)
+        count = count + 1
     end
+    assert(count == expected_count_, "unexpected active lane count")
     print( "\n")
+    return threads
 end
 
 local sleeper = function( name_, seconds_)
@@ -29,7 +27,7 @@ local sleeper = function( name_, seconds_)
         set_debug_threadname( name_)
     end
     -- suspend the lane for the specified duration with a failed linda read
-    wait( seconds_)
+    lanes.sleep(seconds_)
     -- print( "exiting '" .. name_ .. "'")
 end
 
@@ -39,7 +37,7 @@ end
 local g = lanes.gen( "*", sleeper)
 
 -- start a forever-waiting lane (nil timeout)
-g( "forever")
+g( "forever", 'indefinitely')
 
 -- start a lane that will last 2 seconds
 g( "two_seconds", 2)
@@ -47,18 +45,17 @@ g( "two_seconds", 2)
 -- give a bit of time to reach the linda waiting call
 wait( 0.1)
 
--- list the known lanes
-track( "============= START")
+-- list the known lanes (should be living lanes)
+local threads = track( "============= START", 2)
+--     two_seconds                        forever
+assert(threads[1].status == 'waiting' and threads[2].status == 'waiting')
 
 -- wait until "two_seconds has completed"
 wait(2.1)
 
-track( "============= two_seconds dead")
-
--- this will collect the completed lane (and remove it from the tracking queue)
--- collectgarbage()
-
--- track( "============= two_seconds dead (after collectgarbage)")
+local threads = track( "============= two_seconds dead", 2)
+--     two_seconds                        forever
+assert(threads[1].status == 'done' and threads[2].status == 'waiting')
 
 -- start another lane that will last 2 seconds, with the same name
 g( "two_seconds", 2)
@@ -67,6 +64,17 @@ g( "two_seconds", 2)
 wait( 0.1)
 
 -- list the known lanes
-track( "============= ANOTHER")
+-- unless garbage collector cleaned it, we should have 3 lanes
+local threads = track( "============= ANOTHER", 3)
+--     two_seconds #2                     two_seconds #1                  forever
+assert(threads[1].status == 'waiting' and threads[2].status == 'done' and threads[3].status == 'waiting')
+
+-- this will collect the completed lane (and remove it from the tracking queue)
+collectgarbage()
+
+-- list the known lanes
+local threads = track( "============= AFTER COLLECTGARBAGE", 2)
+--     two_seconds #2                     forever
+assert(threads[1].status == 'waiting' and threads[2].status == 'waiting')
 
 print "done"
\ No newline at end of file
-- 
cgit v1.2.3-55-g6feb