feature: implemented the ngx.timer.every() API function for creating recurring timers.

Signed-off-by: Yichun Zhang (agentzh) <[email protected]>

Author: doujiang24

README.markdown

@@ -1471,8 +1471,8 @@ This hook is often used to create per-worker reoccurring timers (via the [ngx.ti
          end
      end
 
-     local ok, err = new_timer(delay, check)
-     if not ok then
+     local hdl, err = new_timer(delay, check)
+     if not hdl then
          log(ERR, "failed to create timer: ", err)
          return
      end
@@ -3217,6 +3217,7 @@ Nginx API for Lua
 * [ngx.thread.kill](#ngxthreadkill)
 * [ngx.on_abort](#ngxon_abort)
 * [ngx.timer.at](#ngxtimerat)
+* [ngx.timer.every](#ngxtimerevery)
 * [ngx.timer.running_count](#ngxtimerrunning_count)
 * [ngx.timer.pending_count](#ngxtimerpending_count)
 * [ngx.config.subsystem](#ngxconfigsubsystem)
@@ -7568,7 +7569,7 @@ See also [lua_check_client_abort](#lua_check_client_abort).
 
 ngx.timer.at
 ------------
-**syntax:** *ok, err = ngx.timer.at(delay, callback, user_arg1, user_arg2, ...)*
+**syntax:** *hdl, err = ngx.timer.at(delay, callback, user_arg1, user_arg2, ...)*
 
 **context:** *init_worker_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, balancer_by_lua*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua**
 
@@ -7594,7 +7595,7 @@ Premature timer expiration happens when the Nginx worker process is
 trying to shut down, as in an Nginx configuration reload triggered by
 the `HUP` signal or in an Nginx server shutdown. When the Nginx worker
 is trying to shut down, one can no longer call `ngx.timer.at` to
-create new timers with nonzero delays and in that case `ngx.timer.at` will return `nil` and
+create new timers with nonzero delays and in that case `ngx.timer.at` will return a "conditional false" value and
 a string describing the error, that is, "process exiting".
 
 Starting from the `v0.9.3` release, it is allowed to create zero-delay timers even when the Nginx worker process starts shutting down.
@@ -7653,6 +7654,9 @@ One can also create infinite re-occurring timers, for instance, a timer getting
  end
 ```
 
+It is recommended, however, to use the [ngx.timer.every](#ngxtimerevery) API function
+instead for creating recurring timers since it is more robust.
+
 Because timer callbacks run in the background and their running time
 will not add to any client request's response time, they can easily
 accumulate in the server and exhaust system resources due to either
@@ -7692,6 +7696,25 @@ This API was first introduced in the `v0.8.0` release.
 
 [Back to TOC](#nginx-api-for-lua)
 
+ngx.timer.every
+---------------
+**syntax:** *hdl, err = ngx.timer.every(delay, callback, user_arg1, user_arg2, ...)*
+
+**context:** *init_worker_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, balancer_by_lua*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua**
+
+Similar to the [ngx.timer.at](#ngxtimerat) API function, but
+
+1. `delay` *cannot* be zero,
+1. timer will be created every `delay` seconds until the current Nginx worker process starts exiting.
+
+When success, returns a "conditional true" value (but not a `true`). Otherwise, returns a "conditional false" value and a string describing the error.
+
+This API also respect the [lua_max_pending_timers](#lua_max_pending_timers) and [lua_max_running_timers](#lua_max_running_timers).
+
+This API was first introduced in the `v0.10.9` release.
+
+[Back to TOC](#nginx-api-for-lua)
+
 ngx.timer.running_count
 -----------------------
 **syntax:** *count = ngx.timer.running_count()*

doc/HttpLuaModule.wiki

@@ -1180,8 +1180,8 @@ This hook is often used to create per-worker reoccurring timers (via the [[#ngx.
             end
         end
 
-        local ok, err = new_timer(delay, check)
-        if not ok then
+        local hdl, err = new_timer(delay, check)
+        if not hdl then
             log(ERR, "failed to create timer: ", err)
             return
         end
@@ -6412,7 +6412,7 @@ This API was first introduced in the <code>v0.7.4</code> release.
 See also [[#lua_check_client_abort|lua_check_client_abort]].
 
 == ngx.timer.at ==
-'''syntax:''' ''ok, err = ngx.timer.at(delay, callback, user_arg1, user_arg2, ...)''
+'''syntax:''' ''hdl, err = ngx.timer.at(delay, callback, user_arg1, user_arg2, ...)''
 
 '''context:''' ''init_worker_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, balancer_by_lua*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*''
 
@@ -6438,7 +6438,7 @@ Premature timer expiration happens when the Nginx worker process is
 trying to shut down, as in an Nginx configuration reload triggered by
 the <code>HUP</code> signal or in an Nginx server shutdown. When the Nginx worker
 is trying to shut down, one can no longer call <code>ngx.timer.at</code> to
-create new timers with nonzero delays and in that case <code>ngx.timer.at</code> will return <code>nil</code> and
+create new timers with nonzero delays and in that case <code>ngx.timer.at</code> will return a "conditional false" value and
 a string describing the error, that is, "process exiting".
 
 Starting from the <code>v0.9.3</code> release, it is allowed to create zero-delay timers even when the Nginx worker process starts shutting down.
@@ -6495,6 +6495,9 @@ One can also create infinite re-occurring timers, for instance, a timer getting
     end
 </geshi>
 
+It is recommended, however, to use the [[#ngx.timer.every|ngx.timer.every]] API function
+instead for creating recurring timers since it is more robust.
+
 Because timer callbacks run in the background and their running time
 will not add to any client request's response time, they can easily
 accumulate in the server and exhaust system resources due to either
@@ -6532,6 +6535,22 @@ You can pass most of the standard Lua values (nils, booleans, numbers, strings,
 
 This API was first introduced in the <code>v0.8.0</code> release.
 
+== ngx.timer.every ==
+'''syntax:''' ''hdl, err = ngx.timer.every(delay, callback, user_arg1, user_arg2, ...)''
+
+'''context:''' ''init_worker_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, balancer_by_lua*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*''
+
+Similar to the [[#ngx.timer.at|ngx.timer.at]] API function, but
+
+# <code>delay</code> ''cannot'' be zero,
+# timer will be created every <code>delay</code> seconds until the current Nginx worker process starts exiting.
+
+When success, returns a "conditional true" value (but not a <code>true</code>). Otherwise, returns a "conditional false" value and a string describing the error.
+
+This API also respect the [[#lua_max_pending_timers|lua_max_pending_timers]] and [[#lua_max_running_timers|lua_max_running_timers]].
+
+This API was first introduced in the <code>v0.10.9</code> release.
+
 == ngx.timer.running_count ==
 '''syntax:''' ''count = ngx.timer.running_count()''