Return-Path:
X-Original-To: apmail-httpd-cvs-archive@www.apache.org
Delivered-To: apmail-httpd-cvs-archive@www.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
by minotaur.apache.org (Postfix) with SMTP id 03173DD02
for ;
Wed, 8 Aug 2012 19:17:05 +0000 (UTC)
Received: (qmail 25036 invoked by uid 500); 8 Aug 2012 19:17:04 -0000
Delivered-To: apmail-httpd-cvs-archive@httpd.apache.org
Received: (qmail 24933 invoked by uid 500); 8 Aug 2012 19:17:04 -0000
Mailing-List: contact cvs-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@httpd.apache.org
list-help:
list-unsubscribe:
List-Post:
List-Id:
Delivered-To: mailing list cvs@httpd.apache.org
Received: (qmail 24923 invoked by uid 99); 8 Aug 2012 19:17:04 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 08 Aug 2012 19:17:04 +0000
X-ASF-Spam-Status: No, hits=-1996.9 required=5.0
tests=ALL_TRUSTED,URI_OBFU_WWW
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 08 Aug 2012 19:16:56 +0000
Received: from eris.apache.org (localhost [127.0.0.1])
by eris.apache.org (Postfix) with ESMTP id E88C323888EA;
Wed, 8 Aug 2012 19:16:12 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Subject: svn commit: r1370899 -
/httpd/httpd/trunk/docs/manual/developer/lua.xml
Date: Wed, 08 Aug 2012 19:16:12 -0000
To: cvs@httpd.apache.org
From: humbedooh@apache.org
X-Mailer: svnmailer-1.0.8-patched
Message-Id: <20120808191612.E88C323888EA@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org
Author: humbedooh
Date: Wed Aug 8 19:16:12 2012
New Revision: 1370899
URL: http://svn.apache.org/viewvc?rev=1370899&view=rev
Log:
Updates:
- Remove reference to functions that are now inside mod_lua
- Remove a lot of "bla bla bla" placeholders
- Add information about optimizing mod_lua for production use
- Fix up the examples a bit
Modified:
httpd/httpd/trunk/docs/manual/developer/lua.xml
Modified: httpd/httpd/trunk/docs/manual/developer/lua.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/developer/lua.xml?rev=1370899&r1=1370898&r2=1370899&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/developer/lua.xml (original)
+++ httpd/httpd/trunk/docs/manual/developer/lua.xml Wed Aug 8 19:16:12 2012
@@ -44,13 +44,11 @@ Stuff about what mod_lua
What we will be discussing in this document
-This document will discuss how you can bla bla bla.
-In the first chapter, we will bla bla
+This document will discuss several cases where mod_lua can be used
+to either ease up a phase of the request processing or create more transparency in
+the logic behind a decision made in a phase.
-
-In the second part of this document, we will be looking at bla bla bla
-
Prerequisites
@@ -65,12 +63,88 @@ and whys of various function calls.
-
+
+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
+
@@ -92,8 +166,6 @@ LuaHookTranslateName /path/too/foo.lua r
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
@@ -115,8 +187,6 @@ end
remap a file to one of two destinations, using a rewrite map.
]]--
-require 'apache2'
-require 'string'
local map = {
photos = {
@@ -181,8 +251,6 @@ LuaHookTranslateName /path/too/foo.lua m
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" },
@@ -216,8 +284,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
@@ -273,9 +339,10 @@ LuaHookAuthChecker /path/too/foo.lua che
-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'
@@ -314,10 +381,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 = {}
@@ -390,6 +457,12 @@ LuaAuthzProvider rights /path/to/lua/scr
+--[[
+ 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" }
@@ -431,9 +504,6 @@ LuaMapHandler ^/portal/([a-z]+)/ /path
-
-
-
HTTPd bindings: String manipulation
@@ -814,28 +884,14 @@ print(unescaped) -- prints "This is a te
Â
-
-apache2.allowoverrides(
- request_rec r
- )
-
-
-Returns the currently allowed overrides for this context (AuthCfg, Options etc)
-
-
-Arguments:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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
@@ -1041,76 +964,6 @@ The password from a basic authorization
Â
-
-apache2.get_limit_req_body(
- request_rec r
- )
-
-
-Returns the current request body size limit
-
-
-Arguments:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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
@@ -1167,114 +1020,6 @@ The entity tag
Â
-
-apache2.options(
- request_rec r
- )
-
-
-Returns the currently allowed options for this context (Indexes, MultiViews etc)
-
-
-Arguments:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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
@@ -1323,43 +1068,6 @@ end
Â
-
-apache2.satisfies(
- request_rec r
- )
-
-
-Returns how the requires lines must be met.
-
-
-Arguments:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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
@@ -1393,39 +1101,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:
-
-
-
-Argument |
-Description |
-
-
-r |
-The mod_lua request handle |
-
-
-filename |
-The 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
@@ -1521,42 +1196,6 @@ True if keepalive can be set, false othe
Â
-
-apache2.some_auth_required(
- request_rec r
- )
-
-
-Returns true if authorization is required for this request
-
-
-Arguments:
-
-
-
-Argument |
-Description |
-
-
-r |
-The 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
-
-Â
-
-
-apache2.banner(
-
- )
-
-
-Returns the server banner
-
-
-Arguments:
-
-None
-
-Return value(s):
-
-The server banner
-
-Â
-
apache2.custom_response(
request_rec r,  number status,  string string
@@ -1858,53 +1470,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:
-
-
-
-Argument |
-Description |
-
-
-r |
-The mod_lua request handle |
-
-
-
-Return value(s):
-
-True if this is the main request, false if it is a sub-request
-
-Â
-
apache2.loaded_modules(
@@ -2103,34 +1668,6 @@ A table with information about the serve
Â
-
-apache2.started(
- request_rec r
- )
-
-
-Returns the time when the server was (re)started
-
-
-Arguments:
-
-
-
-Argument |
-Description |
-
-
-r |
-The mod_lua request handle |
-
-
-
-Return value(s):
-
-The time when the server was (re)started
-
-Â
-
apache2.state_query(
number field
@@ -2412,4 +1949,6 @@ r:puts("delayed")
Â
+
+