docs: added a warning for ngx.var.VARIABLE that memory is allocated in the per-request memory pool. also made it clear why "return" is recommended to be used with ngx.exit(). thanks Antoine.

Author: agentzh

README

@@ -1416,6 +1416,18 @@ Nginx API for Lua
 
         ngx.var.args = nil
 
+    WARNING When reading from an Nginx variable, Nginx will allocate memory
+    in the per-request memory pool which is freed only at request
+    termination. So when you need to read from an Nginx variable repeatedly
+    in your Lua code, cache the Nginx variable value to your own Lua
+    variable, for example,
+
+        local val = ngx.var.some_var
+        --- use the val repeatedly later
+
+    to prevent (temporary) memory leaking within the current request's
+    lifetime.
+
   Core constants
     context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
     content_by_lua*, header_filter_by_lua*, body_filter_by_lua,
@@ -3031,8 +3043,9 @@ Nginx API for Lua
     Note that while this method accepts all HTTP status constants as input,
     it only accepts "NGX_OK" and "NGX_ERROR" of the core constants.
 
-    It is strongly recommended to combine the "return" statement with this
-    call, i.e., "return ngx.exit(...)".
+    It is recommended, though not necessary, to combine the "return"
+    statement with this call, i.e., "return ngx.exit(...)", to give a visual
+    hint to others reading the code.
 
   ngx.eof
     syntax: *ngx.eof()*

README.markdown

@@ -1260,6 +1260,15 @@ Setting `ngx.var.Foo` to a `nil` value will unset the `$Foo` Nginx variable.
     ngx.var.args = nil
 
 
+**WARNING** When reading from an Nginx variable, Nginx will allocate memory in the per-request memory pool which is freed only at request termination. So when you need to read from an Nginx variable repeatedly in your Lua code, cache the Nginx variable value to your own Lua variable, for example,
+
+
+    local val = ngx.var.some_var
+    --- use the val repeatedly later
+
+
+to prevent (temporary) memory leaking within the current request's lifetime.
+
 Core constants
 --------------
 **context:** *init_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**
@@ -2791,7 +2800,7 @@ Number literals can be used directly as the argument, for instance,
 
 Note that while this method accepts all [HTTP status constants](http://wiki.nginx.org/HttpLuaModule#HTTP_status_constants) as input, it only accepts `NGX_OK` and `NGX_ERROR` of the [core constants](http://wiki.nginx.org/HttpLuaModule#core_constants).
 
-It is strongly recommended to combine the `return` statement with this call, i.e., `return ngx.exit(...)`.
+It is recommended, though not necessary, to combine the `return` statement with this call, i.e., `return ngx.exit(...)`, to give a visual hint to others reading the code.
 
 ngx.eof
 -------

doc/HttpLuaModule.wiki

@@ -1212,6 +1212,15 @@ Setting <code>ngx.var.Foo</code> to a <code>nil</code> value will unset the <cod
     ngx.var.args = nil
 </geshi>
 
+'''WARNING''' When reading from an Nginx variable, Nginx will allocate memory in the per-request memory pool which is freed only at request termination. So when you need to read from an Nginx variable repeatedly in your Lua code, cache the Nginx variable value to your own Lua variable, for example,
+
+<geshi lang="lua">
+    local val = ngx.var.some_var
+    --- use the val repeatedly later
+</geshi>
+
+to prevent (temporary) memory leaking within the current request's lifetime.
+
 == Core constants ==
 '''context:''' ''init_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*''
 
@@ -2705,7 +2714,7 @@ Number literals can be used directly as the argument, for instance,
 
 Note that while this method accepts all [[#HTTP status constants|HTTP status constants]] as input, it only accepts <code>NGX_OK</code> and <code>NGX_ERROR</code> of the [[#core constants|core constants]].
 
-It is strongly recommended to combine the <code>return</code> statement with this call, i.e., <code>return ngx.exit(...)</code>.
+It is recommended, though not necessary, to combine the <code>return</code> statement with this call, i.e., <code>return ngx.exit(...)</code>, to give a visual hint to others reading the code.
 
 == ngx.eof ==
 '''syntax:''' ''ngx.eof()''