New API lanes.sleep (bumped version to 3.9.7)

4 files changed, 35 insertions, 6 deletions

diff --git a/CHANGES b/CHANGES
index bba16d3..7c03916 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,9 @@
 CHANGES:
 
+CHANGE 115: BGe 18-sep-14
+   * bumped version to 3.9.7
+   * new function lanes.sleep()
+
 CHANGE 114: BGe 8-Jul-14
    * Postponed _G scan for function lookup database to after on_state_create invocation
    * Fixed a crash when USE_DEBUG_SPEW == 1
diff --git a/docs/index.html b/docs/index.html
index bfd26bb..e8dc94b 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -70,7 +70,7 @@
                         </p>
 
                         <p>
-                                This document was revised on 17-Jun-14, and applies to version <tt>3.9.6</tt>.
+                                This document was revised on 18-Sep-14, and applies to version <tt>3.9.7</tt>.
                         </p>
                 </font>
         </center>
@@ -1291,6 +1291,14 @@ events to a common Linda, but... :).</font>
         The full list of active timers can be obtained. Obviously, this is a snapshot, and non-repeating timers might no longer exist by the time the results are inspected.
 </p>
 
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+        void = lanes.sleep( [seconds|false])
+</pre></td></tr></table>
+
+<p>
+        (Since version 3.9.7) 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 linda used for timers (this linda exists even when timers aren't enabled).
+        Default duration is null, which should only cause a thread context switch.
+</p>
 
 <!-- locks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <hr/>
diff --git a/src/lanes.c b/src/lanes.c
index 1d60700..7f641c3 100644
--- a/src/lanes.c
+++ b/src/lanes.c
@@ -52,7 +52,7 @@
  *      ...
  */
 
-char const* VERSION = "3.9.6";
+char const* VERSION = "3.9.7";
 
 /*
 ===============================================================================
diff --git a/src/lanes.lua b/src/lanes.lua
index 57aa0fe..210f325 100644
--- a/src/lanes.lua
+++ b/src/lanes.lua
@@ -331,12 +331,28 @@ end -- gen()
 
 -- PUBLIC LANES API
 local timer = function() error "timers are not active" end
-local timer_lane = nil
 local timers = timer
+local timer_lane = nil
+
+-- timer_gateway should always exist, even when the settings disable the timers
+local timer_gateway = assert( core.timer_gateway)
+
+-----
+-- <void> = sleep( [seconds_])
+--
+-- 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
+                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
+        return timer_gateway:receive( seconds_, "ac100de1-a696-4619-b2f0-a26de9d58ab8")
+end
+
 
 if settings.with_timers ~= false then
 
-local timer_gateway = assert( core.timer_gateway)
 --
 -- On first 'require "lanes"', a timer lane is spawned that will maintain
 -- timer tables and sleep in between the timer events. All interaction with
@@ -351,8 +367,8 @@ local TGW_KEY= "(timer control)"    -- the key does not matter, a 'weird' key ma
 local TGW_QUERY, TGW_REPLY = "(timer query)", "(timer reply)"
 local first_time_key= "first time"
 
-local first_time= timer_gateway:get(first_time_key) == nil
-timer_gateway:set(first_time_key,true)
+local first_time = timer_gateway:get( first_time_key) == nil
+timer_gateway:set( first_time_key, true)
 
 --
 -- Timer lane; initialize only on the first 'require "lanes"' instance (which naturally
@@ -703,6 +719,7 @@ end
         lanes.timer = timer
         lanes.timer_lane = timer_lane
         lanes.timers = timers
+        lanes.sleep = sleep
         lanes.genlock = genlock
         lanes.now_secs = core.now_secs
         lanes.genatomic = genatomic