fix(sleep) use interruptible sleep function

Author: Tieske

README.md

@@ -96,7 +96,7 @@ The setting `max_use` controls the timer behaviour. The default value is `1000`,
 which means that after each `1000` invocations the timer context is destroyed
 and a new one is generated (this happens transparent to the user).
 
-Optimizing this setting:
+Optimizing this setting (very opinionated/arbitrary!):
 
  * if the timer interval is more than `60` seconds, then keeping the context
    around in idle state for that period is probably more expensive resource wise
@@ -128,6 +128,8 @@ Versioning is strictly based on [Semantic Versioning](https://semver.org/)
   * Feat: provide a stacktrace upon errors in the timer callback
   * Feat: add a `max_use` option. This ensures timer-contexts are recycled to
     prevent memory leaks.
+  * Feat: adds a new function `sleep` similar to `ngx.sleep` except that it is
+    interrupted on worker exit.
   * Fix: now accounts for execution time of the handler, when rescheduling.
 
 ### 1.1.0 (6-Nov-2020)

lib/resty/timer.lua

@@ -14,7 +14,7 @@ local anchor_registry = {}
 local gc_registry = setmetatable({},{ __mode = "v" })
 local timer_id = 0
 local now = ngx.now
-local sleep = ngx.sleep
+local ngx_sleep = ngx.sleep
 local exiting = ngx.worker.exiting
 
 local KEY_PREFIX    = "[lua-resty-timer]"
@@ -23,6 +23,64 @@ local CANCEL_GC     = "GC"
 local CANCEL_SYSTEM = "SYSTEM"
 local CANCEL_USER   = "USER"
 
+local sleep do
+  -- create a 10yr timer. Will only be called when the worker exits with
+  -- `premature` set. The callback will release a global semaphore to wake up
+  -- sleeping threads
+  local sema = assert(require("ngx.semaphore").new())
+  assert(timer_at(10*365*24*60*60, function()
+    sema:post(math.huge)
+
+    -- TODO: remove the sleep(0), it's a hack around semaphores
+    -- not being released properly, an Openresty bug.
+    -- See https://github.com/openresty/lua-resty-core/issues/337
+    ngx_sleep(0)
+  end))
+
+  --- A `sleep` function that exits early on worker exit. The same as `ngx.sleep`
+  -- except that it will be interrupted when the current worker starts exiting.
+  -- Calling this function after the worker started exiting will immediately
+  -- return (after briefly yielding with a `ngx.sleep(0)`).
+  -- @param delay same as `ngx.sleep()`; delay in seconds.
+  -- @return `true` if finished, `false` if returned early, or nil+err (under
+  -- the hood it will return `not ngx.worker.exiting()`).
+  -- @usage if not sleep(5) then
+  --   -- sleep was interrupted, exit now
+  --   return nil, "exiting"
+  -- end
+  --
+  -- -- do stuff
+  function sleep(delay)
+    if type(delay) ~= "number" then
+      error("Bad argument #1, expected number, got " .. type(delay), 2)
+    end
+
+    if delay <= 0 then
+      -- no delay, just yield and return
+      ngx_sleep(delay)
+      return not exiting()
+    end
+
+    local ok, err = sema:wait(delay)
+    if err == "timeout" then
+      -- the sleep was finished
+      return not exiting()
+    end
+
+    -- each call to sleep should at a minimum at least yield, to prevent
+    -- dead-locks elsewhere, so forcefully yield here.
+    ngx_sleep(0)
+
+    if ok then
+      -- we're exiting early because resources were posted to the semaphore
+      return not exiting()
+    end
+
+    ngx.log(ngx.ERR, "waiting for semaphore failed: ", err)
+    return nil, err
+  end
+end
+
 
 
 --- Cancel the timer.
@@ -141,10 +199,7 @@ local function handler(premature, id)
     end
 
     -- existing timer recurring, so keep this thread alive and just sleep
-    if not exiting() then
-      sleep(next_interval)
-    end
-    premature = exiting()
+    premature = not sleep(next_interval)
   end  -- while
 end
 
@@ -160,12 +215,12 @@ end
 --
 -- * `jitter` : (optional, number) variable interval to add to the first interval, default 0.
 -- If set to 1 second then the first interval will be set between `interval` and `interval + 1`.
--- This makes sure if large numbers of timers are used, their execution gets randomly
+-- This makes sure if a large number of timers are used, their execution gets randomly
 -- distributed.
 --
 -- * `immediate` : (boolean) will do the first run immediately (the initial
 -- interval will be set to 0 seconds). This option requires the `recurring` option.
--- The first run will not include the `jitter` interval, it will be added to second run.
+-- The first run will not include the `jitter` interval, it will be added to the second run.
 --
 -- * `detached` : (boolean) if set to `true` the timer will keep running detached, if
 -- set to `false` the timer will be garbage collected unless anchored
@@ -340,6 +395,7 @@ end
 return setmetatable(
   {
     new = new,
+    sleep = sleep,
     CANCEL_GC = CANCEL_GC,
     CANCEL_SYSTEM = CANCEL_SYSTEM,
     CANCEL_USER = CANCEL_USER,