From: Daniel Gruno Date: Wed, 8 Aug 2012 19:18:41 +0000 (+0000) Subject: xforms X-Git-Tag: 2.5.0-alpha~6459 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7f96b2532dc6b4403fcb2ac376ea1651017b2935;p=thirdparty%2Fapache%2Fhttpd.git xforms git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1370901 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/developer/lua.html.en b/docs/manual/developer/lua.html.en index 4f1787c10aa..31504243745 100644 --- a/docs/manual/developer/lua.html.en +++ b/docs/manual/developer/lua.html.en @@ -28,6 +28,7 @@ additional ways of using mod_lua for writing hooks and scripts.

top
+
+

Optimizing mod_lua for production servers

+ +

Setting a scope for Lua states

+

+Setting the right LuaScope setting +for your Lua scripts can be essential to your server's +performance. By default, the scope is set to once, which means +that every call to a Lua script will spawn a new Lua state that handles that +script and is destroyed immediately after. This option keeps the memory +footprint of mod_lua low, but also affects the processing speed of a request. +If you have the memory to spare, you can set the scope to thread, +which will make mod_lua spawn a Lua state that lasts the entirity of a thread's +lifetime, speeding up request processing by 2-3 times. Since mod_lua will create +a state for each script, this may be an expensive move, memory-wise, so to +compromise between speed and memory usage, you can choose the server +option to create a pool of Lua states to be used. Each request for a Lua script or +a hook function will then acquire a state from the pool and release it back when it's +done using it, allowing you to still gain a significant performance increase, while +keeping your memory footprint low. Some examples of possible settings are: +

-LoadModule lua_module modules/mod_lua.so
+LuaScope once
+LuaScope thread
+LuaScope server 5 40
+

+As a general rule of thumb: If your server has none to low usage, use once +or request, if your server has low to medium usage, use the server +pool, and if it has high usage, use the thread setting. As your server's +load increases, so will the number of states being actively used, and having your scope +set to once/request/conn will stop being beneficial to your memory footprint. +

+

+Note: The min and max settings for the +server scope denotes the minimum and maximum states to keep in a pool per +server process, so keep this below your ThreadsPerChild limit. +

+ + +

Using code caching

+

+By default, mod_lua stats each Lua script to determine whether a reload +(and thus, a re-interpretation and re-compilation) of a script is required. This is managed +through the LuaCodeCache directive. If you are running +your scripts on a production server, and you do not need to update them regularly, it may be +advantageous to set this directive to the forever value, which will cause mod_lua +to skip the stat process and always reuse the compiled byte-code from the first access to the +script, thus speeding up the processing. For Lua hooks, this can prove to increase peformance, +while for scripts handled by the lua-script handler, the increase in performance +may be negligible, as files httpd will stat the files regardless. +

+ + +

Keeping the scope clean

+

+For maximum performance, it is generally recommended that any initialization of libraries, +constants and master tables be kept outside the handle's scope: +

+
+--[[ This is good practice ]]--
+require "string"
+require "someLibrary"
+local masterTable = {}
+local constant = "Foo bar baz"
+
+function handle(r)
+    do_stuff()
+end
+
+ +
+--[[ This is bad practice ]]--
+require "string"
+
+function handle(r)
+    require "someLibrary"
+    local masterTable = {}
+    local constant = "Foo bar baz"
+    do_stuff()
+end
+
@@ -101,8 +178,6 @@ LuaHookTranslateName /path/too/foo.lua remap This example will rewrite /foo/test.bar to the physical file /internal/test, somewhat like how mod_alias works. ]]-- -require 'apache2' -require 'string' function remap(r) -- Test if the URI matches our criteria @@ -125,8 +200,6 @@ end remap a file to one of two destinations, using a rewrite map. ]]-- -require 'apache2' -require 'string' local map = { photos = { @@ -190,8 +263,6 @@ LuaHookTranslateName /path/too/foo.lua mass_vhost This example will check a map for a virtual host and rewrite filename and document root accordingly. ]]-- -require 'apache2' -require 'string' local vhosts = { { domain = "example.com", home = "/www/example.com" }, @@ -226,8 +297,6 @@ end 60 seconds before checking for updates. For best performance, such scripts should generally be run with LuaScope set to 'thread' or 'server' ]]-- -require 'apache2' -require 'string' local cached_vhosts = {} local timeout = 60 @@ -282,9 +351,10 @@ LuaHookAuthChecker /path/too/foo.lua check_auth 
-require 'apache2'
-require 'string'
-
+--[[ 
+     A simple authentication hook that checks a table containing usernames and
+     passwords of two accounts.
+]]--
 local accounts = {
     bob  = 'somePassword',
     jane = 'Iloveponies'
@@ -324,10 +394,10 @@ end
 
 
 
--- An advanced authentication checker with a database backend,
--- caching account entries for 1 minute
-require 'apache2'
-require 'string'
+--[[ 
+     An advanced authentication checker with a database backend,
+     caching account entries for 1 minute
+]]--
 
 local timeout = 60 -- Set account info to be refreshed every minute
 local accounts = {}
@@ -402,6 +472,12 @@ LuaAuthzProvider rights /path/to/lua/script.lua rights_handler
 
 
 
+--[[ 
+     This script has two user groups; members and admins, and whichever 
+     is refered to by the "Require rights" directive is checked to see
+     if the authenticated user belongs to this group.
+]]--
+
 local members = { "rbowen", "humbedooh", "igalic", "covener" }
 local admins = { "humbedooh" }
 
@@ -827,28 +903,14 @@ print(unescaped) -- prints "This is a test"
 
HTTPd bindings: Request handling

 
 

-apache2.sendfile
-

-apache2.port
-

-apache2.options
-

-apache2.allowoverrides
-

 apache2.requestbody
 

 apache2.add_input_filter
 

 apache2.get_basic_auth_pw
 

-apache2.get_limit_req_body
-

-apache2.request_has_body
-

 apache2.set_document_root
 

-apache2.some_auth_required
-

 apache2.set_context_prefix
 

 apache2.get_server_name_for_url
@@ -857,18 +919,8 @@ print(unescaped) -- prints "This is a test"
 

 apache2.make_etag
 

-apache2.flush
-

 apache2.send_interim_response
 

-apache2.get_server_name
-

-apache2.auth_type
-

-apache2.auth_name
-

-apache2.satisfies
-

 

 
apache2.add_input_filter(
     request_rec r,  string filter
@@ -904,131 +956,6 @@ apache2.add_input_filter(r, "SPAM_FILTER") -- Check input for spam..?
 
 
 

 
-
apache2.allowoverrides(
-    request_rec r
-    )
-    

-
-

-Returns the currently allowed overrides for this context (AuthCfg, Options etc)
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-The currently allowed overrides for this context (AuthCfg, Options etc)
-        

-

-Example:
-

-
-local ctx = apache2.allowoverrides(r)
-if ctx:match("AuthCfg") then
-    r:puts("You are allowed to override AuthCfg stuff in your .htaccess")
-end
-        

-
-
 

-
-
apache2.auth_name(
-    request_rec r
-    )
-    

-
-

-Returns the current Authorization realm
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-The current authorization realm
-        

-
 

-
-
apache2.auth_type(
-    request_rec r
-    )
-    

-
-

-Returns the current authentication type used in the request
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-The current Authorization type used in the request
-        

-
 

-
-
apache2.flush(
-    request_rec r
-    )
-    

-
-

-Flushes the content buffer, writing everything to the client immediately.
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Example:
-

-
-r:puts("This is buffered")
-apache2.flush(r) -- now it's written to the client.
-        

-
-
 

-
 
apache2.get_basic_auth_pw(
     request_rec r
     )
@@ -1057,78 +984,6 @@ The password from a basic authorization request or nil if none was supplied
         

 
 

 
-
apache2.get_limit_req_body(
-    request_rec r
-    )
-    

-
-

-Returns the current request body size limit
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-The current request body size limit
-        

-

-Example:
-

-
-local limit = apache2.get_limit_req_body(r)
-r:puts("You can't upload files bigger than ", limit, " bytes!")
-        

-
-
 

-
-
apache2.get_server_name(
-    request_rec r
-    )
-    

-
-

-Returns the current server name from the request
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-The server name
-        

-

-Example:
-

-
-local name = apache2.get_server_name(r)
-r:puts("The ServerName is set to: ", name)
-        

-
-
 

-
 
apache2.get_server_name_for_url(
     request_rec r
     )
@@ -1185,117 +1040,6 @@ The entity tag
         

 
 

 
-
apache2.options(
-    request_rec r
-    )
-    

-
-

-Returns the currently allowed options for this context (Indexes, MultiViews etc)
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-The currently allowed options for this context.
-        

-

-Example:
-

-
-local ctx = apache2.options(r)
-if ctx:match("MultiViews") then
-    r:puts("MultiViews is enabled!")
-end
-        

-
-
 

-
-
apache2.port(
-    request_rec r
-    )
-    

-
-

-Returns the port currently being used by the request
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-The current port used by the request
-        

-

-Example:
-

-
-local port = apache2.port(r)
-r:puts("We are listening on port ", port)
-        

-
-
 

-
-
apache2.request_has_body(
-    request_rec r
-    )
-    

-
-

-Returns true if the request has a body(POST/PUT), false otherwise
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-True if the request has a body(POST/PUT), false otherwise
-        

-

-Example:
-

-
-if apache2.request_has_body(r) then
-    -- do stuff with the req body
-end
-        

-
-
 

-
 
apache2.requestbody(
     request_rec r,  number size,  string filename
     )
@@ -1345,44 +1089,6 @@ end
 
 
 

 
-
apache2.satisfies(
-    request_rec r
-    )
-    

-
-

-Returns how the requires lines must be met.
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-How the requirements must be met (SATISFY_ANY, SATISFY_ALL, SATISFY_NOSPEC).
-        

-

-Example:
-

-
-local how = apache2.satisfies(r)
-if how == "SATISFY_ANY" then
-    -- ...
-end
-        

-
-
 

-
 
apache2.send_interim_response(
     request_rec r,  boolean send_headers
     )
@@ -1417,40 +1123,6 @@ apache2.send_interim_response(r, false)
 
 
 

 
-
apache2.sendfile(
-    request_rec r,  string filename
-    )
-    

-
-

-Sends a file to the client via sendfile() if possible.
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle
filenameThe file to send

-

-Example:
-

-
-apache2.sendfile(r, "/foo/bar/test.png") -- sends /foo/bar/test.png via sendfile
-        

-
-
 

-
 
apache2.set_context_prefix(
     request_rec r,  string prefix,  string document
     )
@@ -1547,43 +1219,6 @@ True if keepalive can be set, false otherwise
         

 
 

 
-
apache2.some_auth_required(
-    request_rec r
-    )
-    

-
-

-Returns true if authorization is required for this request
-        

-

-Arguments:
-

-
-
-
-
-
-
-
-
-
-
ArgumentDescription
rThe mod_lua request handle

-

-Return value(s):
-

-True if auth is required, false if not.
-        

-

-Example:
-

-
-if apache2.some_auth_required(r) then
-    print("debug: auth is required for this request\n")
-end
-        

-
-
 

-
top

HTTPd bindings: Parser functions

@@ -1735,8 +1370,6 @@ end

apache2.add_version_component
-apache2.banner -
apache2.mpm_query
apache2.terminate @@ -1745,14 +1378,8 @@ end
apache2.scoreboard_worker
-apache2.started -
apache2.module_info
-apache2.get_server_built -
-apache2.is_initial_req -
apache2.loaded_modules
apache2.runtime_dir_relative @@ -1802,25 +1429,6 @@ end

 

-

apache2.banner( - - ) -

- -

-Returns the server banner -

-

-Arguments: -

-

None

-

-Return value(s): -
-The server banner -

-

 

-

apache2.custom_response( request_rec r,  number status,  string string ) @@ -1891,53 +1499,6 @@ end

 

-

apache2.get_server_built( - - ) -

- -

-Returns the date the server was built -

-

-Arguments: -

-

None

-

-Return value(s): -
-The date the server was built -

-

 

- -

apache2.is_initial_req( - request_rec r - ) -

- -

-Returns true if this is the main request, false if it is a sub-request -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-True if this is the main request, false if it is a sub-request -

-

 

-

apache2.loaded_modules( ) @@ -2136,34 +1697,6 @@ A table with information about the server program

 

-

apache2.started( - request_rec r - ) -

- -

-Returns the time when the server was (re)started -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The time when the server was (re)started -

-

 

-

apache2.state_query( number field )