updated docs to reflect changes (including documenting ngx.sleep.)

2012-05-29 16:01:18 +08:00 · 2012-05-29 16:01:18 +08:00 · 2362917a68
--- a/36
+++ b/36
@ -8,8 +8,8 @@ Status
    This module is under active development and is production ready.

 Version
-    This document describes ngx_lua v0.5.0rc28
-    (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 16
+    This document describes ngx_lua v0.5.0rc29
+    (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 28
    May 2012.

 Synopsis
@ -535,9 +535,12 @@ Directives
    Here the Lua code "ngx.exit(503)" will never run. This will be the case
    if "rewrite ^ /bar last" is used as this will similarly initiate an
    internal redirection. If the "break" modifier is used instead, there
-    will be no internal redirection and the rewrite_by_lua code will be
+    will be no internal redirection and the "rewrite_by_lua" code will be
    executed.

+    The "rewrite_by_lua" code will always run at the end of the "rewrite"
+    request-processing phase unless rewrite_by_lua_no_postpone is turned on.
+
  rewrite_by_lua_file
    syntax: *rewrite_by_lua_file <path-to-lua-script-file>*

@ -562,6 +565,10 @@ Directives
    can be temporarily disabled during development by switching
    lua_code_cache "off" in "nginx.conf" to avoid reloading Nginx.

+    The "rewrite_by_lua_file" code will always run at the end of the
+    "rewrite" request-processing phase unless rewrite_by_lua_no_postpone is
+    turned on.
+
  access_by_lua
    syntax: *access_by_lua <lua-script-str>*

@ -2509,6 +2516,18 @@ Nginx API for Lua

    Explicitly specify the end of the response output stream.

+  ngx.sleep
+    syntax: *ngx.sleep(seconds)*
+
+    context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
+
+    Sleeps for the specified seconds non-blockingly. One can specify time
+    resolution up to 0.001 seconds (i.e., one milliseconds).
+
+    Behind the scene, this method makes use of the Nginx timers.
+
+    This method was introduced in the "0.5.0rc30" release.
+
  ngx.escape_uri
    syntax: *newstr = ngx.escape_uri(str)*

@ -4221,13 +4240,6 @@ Bugs and Patches

 TODO
  Short Term
-    *   implement the "ngx.sleep(time)" Lua API. (For now, use
-        ngx.location.capture with [[HttpEchoModule]]'s echo_sleep config
-        directive instead.)
-
-    *   implement the "ngx.worker.get_pid()" Lua API. (For now, use
-        "ngx.var.pid" directly.)
-
    *   implement LuaSocket UDP API
        (<http://w3.impa.br/~diego/software/luasocket/udp.html>) in our
        cosocket API.
@ -4251,8 +4263,8 @@ TODO
        methods, to allow micro performance tuning on the user side.

  Longer Term
-    *   add the "lua_require" directive to load module into main thread's
-        globals.
+    *   add the "lua_require" directive to load module into the Lua main
+        thread's globals.

    *   add Lua code automatic time slicing support by yielding and resuming
        the Lua VM actively via Lua's debug hooks.
--- a/README.markdown
+++ b/README.markdown
@ -18,7 +18,7 @@ This module is under active development and is production ready.
 Version
 =======

-This document describes ngx_lua [v0.5.0rc28](https://github.com/chaoslawful/lua-nginx-module/tags) released on 16 May 2012.
+This document describes ngx_lua [v0.5.0rc29](https://github.com/chaoslawful/lua-nginx-module/tags) released on 28 May 2012.

 Synopsis
 ========
@ -503,7 +503,9 @@ If the [HttpRewriteModule](http://wiki.nginx.org/HttpRewriteModule)'s [rewrite](
    }


-Here the Lua code `ngx.exit(503)` will never run. This will be the case if `rewrite ^ /bar last` is used as this will similarly initiate an internal redirection. If the `break` modifier is used instead, there will be no internal redirection and the rewrite_by_lua code will be executed.
+Here the Lua code `ngx.exit(503)` will never run. This will be the case if `rewrite ^ /bar last` is used as this will similarly initiate an internal redirection. If the `break` modifier is used instead, there will be no internal redirection and the `rewrite_by_lua` code will be executed.
+
+The `rewrite_by_lua` code will always run at the end of the `rewrite` request-processing phase unless [rewrite_by_lua_no_postpone](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua_no_postpone) is turned on.

 rewrite_by_lua_file
 -------------------
@ -522,6 +524,8 @@ When a relative path like `foo/bar.lua` is given, they will be turned into the a

 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached and the Nginx config must be reloaded each time the Lua source file is modified. The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache) `off` in `nginx.conf` to avoid reloading Nginx.

+The `rewrite_by_lua_file` code will always run at the end of the `rewrite` request-processing phase unless [rewrite_by_lua_no_postpone](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua_no_postpone) is turned on.
+
 access_by_lua
 -------------

@ -2380,6 +2384,18 @@ ngx.eof

 Explicitly specify the end of the response output stream.

+ngx.sleep
+---------
+**syntax:** *ngx.sleep(seconds)*
+
+**context:** *rewrite_by_lua*, access_by_lua*, content_by_lua**
+
+Sleeps for the specified seconds non-blockingly. One can specify time resolution up to 0.001 seconds (i.e., one milliseconds).
+
+Behind the scene, this method makes use of the Nginx timers.
+
+This method was introduced in the `0.5.0rc30` release.
+
 ngx.escape_uri
 --------------
 **syntax:** *newstr = ngx.escape_uri(str)*
@ -3811,8 +3827,6 @@ TODO

 Short Term
 ----------
-* implement the `ngx.sleep(time)` Lua API. (For now, use [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) with [HttpEchoModule](http://wiki.nginx.org/HttpEchoModule)'s [echo_sleep](http://wiki.nginx.org/HttpEchoModule#echo_sleep) config directive instead.)
-* implement the `ngx.worker.get_pid()` Lua API. (For now, use `ngx.var.pid` directly.)
 * implement [LuaSocket UDP API](http://w3.impa.br/~diego/software/luasocket/udp.html) in our cosocket API.
 * implement the SSL cosocket API.
 * implement the `ngx.re.split` method.
@ -3824,7 +3838,7 @@ Short Term

 Longer Term
 -----------
-* add the `lua_require` directive to load module into main thread's globals.
+* add the `lua_require` directive to load module into the Lua main thread's globals.
 * add Lua code automatic time slicing support by yielding and resuming the Lua VM actively via Lua's debug hooks.
 * make [set_by_lua](http://wiki.nginx.org/HttpLuaModule#set_by_lua), [header_filter_by_lua](http://wiki.nginx.org/HttpLuaModule#header_filter_by_lua), and their variants use the same mechanism as [content_by_lua](http://wiki.nginx.org/HttpLuaModule#content_by_lua), [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua), [access_by_lua](http://wiki.nginx.org/HttpLuaModule#access_by_lua), and their variants.
 * add coroutine API back to the Lua user land.
--- a/doc/HttpLuaModule.wiki
+++ b/doc/HttpLuaModule.wiki
@ -10,7 +10,7 @@ This module is under active development and is production ready.

 = Version =

-This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.0rc28] released on 16 May 2012.
+This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.0rc29] released on 28 May 2012.

 = Synopsis =
 <geshi lang="nginx">
@ -483,7 +483,9 @@ If the [[HttpRewriteModule]]'s [[HttpRewriteModule#rewrite|rewrite]] directive i
    }
 </geshi>

-Here the Lua code <code>ngx.exit(503)</code> will never run. This will be the case if <code>rewrite ^ /bar last</code> is used as this will similarly initiate an internal redirection. If the <code>break</code> modifier is used instead, there will be no internal redirection and the rewrite_by_lua code will be executed.
+Here the Lua code <code>ngx.exit(503)</code> will never run. This will be the case if <code>rewrite ^ /bar last</code> is used as this will similarly initiate an internal redirection. If the <code>break</code> modifier is used instead, there will be no internal redirection and the <code>rewrite_by_lua</code> code will be executed.
+
+The <code>rewrite_by_lua</code> code will always run at the end of the <code>rewrite</code> request-processing phase unless [[#rewrite_by_lua_no_postpone|rewrite_by_lua_no_postpone]] is turned on.

 == rewrite_by_lua_file ==

@ -501,6 +503,8 @@ When a relative path like <code>foo/bar.lua</code> is given, they will be turned

 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached and the Nginx config must be reloaded each time the Lua source file is modified. The Lua code cache can be temporarily disabled during development by switching [[#lua_code_cache|lua_code_cache]] <code>off</code> in <code>nginx.conf</code> to avoid reloading Nginx.

+The <code>rewrite_by_lua_file</code> code will always run at the end of the <code>rewrite</code> request-processing phase unless [[#rewrite_by_lua_no_postpone|rewrite_by_lua_no_postpone]] is turned on.
+
 == access_by_lua ==

 '''syntax:''' ''access_by_lua <lua-script-str>''
@ -2306,6 +2310,17 @@ It's strongly recommended to combine the <code>return</code> statement with this

 Explicitly specify the end of the response output stream.

+== ngx.sleep ==
+'''syntax:''' ''ngx.sleep(seconds)''
+
+'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
+
+Sleeps for the specified seconds non-blockingly. One can specify time resolution up to 0.001 seconds (i.e., one milliseconds).
+
+Behind the scene, this method makes use of the Nginx timers.
+
+This method was introduced in the <code>0.5.0rc30</code> release.
+
 == ngx.escape_uri ==
 '''syntax:''' ''newstr = ngx.escape_uri(str)''

@ -3677,8 +3692,6 @@ Please report bugs or submit patches by:
 = TODO =

 == Short Term ==
-* implement the <code>ngx.sleep(time)</code> Lua API. (For now, use [[#ngx.location.capture|ngx.location.capture]] with [[HttpEchoModule]]'s [[HttpEchoModule#echo_sleep|echo_sleep]] config directive instead.)
-* implement the <code>ngx.worker.get_pid()</code> Lua API. (For now, use <code>ngx.var.pid</code> directly.)
 * implement [http://w3.impa.br/~diego/software/luasocket/udp.html LuaSocket UDP API] in our cosocket API.
 * implement the SSL cosocket API.
 * implement the <code>ngx.re.split</code> method.
@ -3689,7 +3702,7 @@ Please report bugs or submit patches by:
 * add <code>ignore_resp_headers</code>, <code>ignore_resp_body</code>, and <code>ignore_resp</code> options to [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]] methods, to allow micro performance tuning on the user side.

 == Longer Term ==
-* add the <code>lua_require</code> directive to load module into main thread's globals.
+* add the <code>lua_require</code> directive to load module into the Lua main thread's globals.
 * add Lua code automatic time slicing support by yielding and resuming the Lua VM actively via Lua's debug hooks.
 * make [[#set_by_lua|set_by_lua]], [[#header_filter_by_lua|header_filter_by_lua]], and their variants use the same mechanism as [[#content_by_lua|content_by_lua]], [[#rewrite_by_lua|rewrite_by_lua]], [[#access_by_lua|access_by_lua]], and their variants.
 * add coroutine API back to the Lua user land.