You are viewing a plain text version of this content. The canonical link for it is here.
Posted to rivet-dev@tcl.apache.org by mx...@apache.org on 2012/10/17 00:15:58 UTC
svn commit: r1399021 - in /tcl/rivet/branches/2.1: ChangeLog doc/
doc/convert_examples.tcl.in doc/examples-sgml/hello1.rvt
doc/xml/commands.xml doc/xml/directives.xml doc/xml/examples.xml
doc/xml/install.xml doc/xml/request.xml
Author: mxmanghi
Date: Tue Oct 16 22:15:57 2012
New Revision: 1399021
URL: http://svn.apache.org/viewvc?rev=1399021&view=rev
Log:
* doc/xml/directives.xml,doc/xml/commands.xml,doc/xml/install.xml,doc/xml/examples.xml,
doc/xml/request.xml,doc/convert_examples.tcl.in,doc/examples-sgml/hello1.rvt: Trying to
improve the manual revising and extending it
Modified:
tcl/rivet/branches/2.1/ChangeLog
tcl/rivet/branches/2.1/doc/ (props changed)
tcl/rivet/branches/2.1/doc/convert_examples.tcl.in
tcl/rivet/branches/2.1/doc/examples-sgml/hello1.rvt
tcl/rivet/branches/2.1/doc/xml/commands.xml
tcl/rivet/branches/2.1/doc/xml/directives.xml
tcl/rivet/branches/2.1/doc/xml/examples.xml
tcl/rivet/branches/2.1/doc/xml/install.xml
tcl/rivet/branches/2.1/doc/xml/request.xml
Modified: tcl/rivet/branches/2.1/ChangeLog
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/2.1/ChangeLog?rev=1399021&r1=1399020&r2=1399021&view=diff
==============================================================================
--- tcl/rivet/branches/2.1/ChangeLog (original)
+++ tcl/rivet/branches/2.1/ChangeLog Tue Oct 16 22:15:57 2012
@@ -1,3 +1,8 @@
+2012-10-16 Massimo Manghi <mx...@apache.org>
+ * doc/xml/directives.xml,doc/xml/commands.xml,doc/xml/install.xml,doc/xml/examples.xml,
+ doc/xml/request.xml,doc/convert_examples.tcl.in,doc/examples-sgml/hello1.rvt: Trying to
+ improve the manual revising and extending it
+
2012-10-01 Massimo Manghi <mx...@apache.org>
* doc/xml/request.xml,doc/xml/install.xml: attempting to improve the documentation
* doc/images/: Adding missing icons
Propchange: tcl/rivet/branches/2.1/doc/
------------------------------------------------------------------------------
Merged /tcl/rivet/trunk/doc:r1392441-1399019
Modified: tcl/rivet/branches/2.1/doc/convert_examples.tcl.in
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/2.1/doc/convert_examples.tcl.in?rev=1399021&r1=1399020&r2=1399021&view=diff
==============================================================================
--- tcl/rivet/branches/2.1/doc/convert_examples.tcl.in (original)
+++ tcl/rivet/branches/2.1/doc/convert_examples.tcl.in Tue Oct 16 22:15:57 2012
@@ -44,7 +44,7 @@ foreach example $source_examples {
puts "$example needs rebuild"
- set example_text [::rivet::read_file $example]
+ set example_text [string trim [::rivet::read_file $example]]
set example_sgml_fid [open $example_sgml w+]
puts $example_sgml_fid [::rivet::escape_sgml_chars $example_text]
Modified: tcl/rivet/branches/2.1/doc/examples-sgml/hello1.rvt
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/2.1/doc/examples-sgml/hello1.rvt?rev=1399021&r1=1399020&r2=1399021&view=diff
==============================================================================
--- tcl/rivet/branches/2.1/doc/examples-sgml/hello1.rvt (original)
+++ tcl/rivet/branches/2.1/doc/examples-sgml/hello1.rvt Tue Oct 16 22:15:57 2012
@@ -1,2 +1 @@
<?= "Hello World" ?>
-
Modified: tcl/rivet/branches/2.1/doc/xml/commands.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/2.1/doc/xml/commands.xml?rev=1399021&r1=1399020&r2=1399021&view=diff
==============================================================================
--- tcl/rivet/branches/2.1/doc/xml/commands.xml (original)
+++ tcl/rivet/branches/2.1/doc/xml/commands.xml Tue Oct 16 22:15:57 2012
@@ -25,6 +25,37 @@
that commands be specified with their fully qualified names.
</para>
</section>
+ <refentry id="shorthand">
+ <refnamediv>
+ <refname><?= ... ?></refname>
+ <refpurpose>
+ Shorthand construct for single strings output
+ </refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command><?= <arg choice="plain">$string</arg> ?></command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ This construct is a simplified form to print a single string wherever
+ needed in a <arg>.rvt</arg> template. The contruct is equivalent to
+ writing the following line of Tcl code
+ </para>
+ <programlisting>put -nonewline $string</programlisting>
+ <para>
+ The <arg>string</arg> argument to the shorthand construct can
+ be any Tcl command returning a value
+ </para>
+ <para>
+ See <xref linkend="hello_world">Hello World</xref> or
+ <xref linkend="variable_access">Variable Access</xref>
+ </para>
+ </refsect1>
+ </refentry>
+
<refentry id="abort_code">
<refnamediv>
<refname>abort_code</refname>
@@ -81,8 +112,9 @@
specified in the configuration. The value of the
argument <arg>abort code</arg> can be retrieved with the
<command>abort_code</command> command during the
- execution of AbortScript or AfterEveryScript, allowing
- the script to take appropriate actions in order to deal
+ execution of <link linkend="directives">AbortScript or
+ AfterEveryScript</link>,
+ allowing the script to take appropriate actions in order to deal
with the cause of the abort.
</para>
<para>
@@ -331,55 +363,59 @@
<!-- Reference page for command 'cookie' -->
<refentry id="cookie">
<refnamediv>
- <refname>cookie</refname>
- <refpurpose>get, set and delete cookies.</refpurpose>
+ <refname>cookie</refname>
+ <refpurpose>get, set and delete cookies.</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <cmdsynopsis>
- <command>::rivet::cookie</command>
- <arg>set</arg>
- <arg><replaceable>cookieName</replaceable></arg>
- <arg><replaceable><optional>cookiValue</optional></replaceable></arg>
- <arg>-days <replaceable>expireInDays</replaceable></arg>
- <arg>-hours <replaceable>expireInHours</replaceable></arg>
- <arg>-minutes <replaceable>expireInMinutes</replaceable></arg>
- <arg>-expires <replaceable>Wdy, DD-Mon-YYYY HH:MM:SS GMT</replaceable></arg>
- <arg>-path <replaceable>uriPathCookieAppliesTo</replaceable></arg>
- <arg>-secure <replaceable>1/0</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>::rivet::cookie</command>
- <arg>get</arg>
- <arg><replaceable>cookieName</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>::rivet::cookie</command>
- <arg>delete</arg>
- <arg><replaceable>cookieName</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>::rivet::cookie</command>
- <arg>unset</arg>
- <arg><replaceable>cookieName</replaceable></arg>
- </cmdsynopsis>
+ <cmdsynopsis>
+ <command>::rivet::cookie</command>
+ <arg>set</arg>
+ <arg><replaceable>cookieName</replaceable></arg>
+ <arg><replaceable><optional>cookiValue</optional></replaceable></arg>
+ <arg>-days <replaceable>expireInDays</replaceable></arg>
+ <arg>-hours <replaceable>expireInHours</replaceable></arg>
+ <arg>-minutes <replaceable>expireInMinutes</replaceable></arg>
+ <arg>-expires <replaceable>Wdy, DD-Mon-YYYY HH:MM:SS GMT</replaceable></arg>
+ <arg>-path <replaceable>uriPathCookieAppliesTo</replaceable></arg>
+ <arg>-secure <replaceable>1/0</replaceable></arg>
+ <arg>-HttpOnly <replaceable>1/0</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>::rivet::cookie</command>
+ <arg>get</arg>
+ <arg><replaceable>cookieName</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>::rivet::cookie</command>
+ <arg>delete</arg>
+ <arg><replaceable>cookieName</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>::rivet::cookie</command>
+ <arg>unset</arg>
+ <arg><replaceable>cookieName</replaceable></arg>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
- <title>Description</title>
- <para>
- <command>cookie</command> gets, sets, unsets or deletes a cookie. When you
- get a cookie, the command returns the value of the cookie,
- or an empty string if no cookie exists.
- </para>
- <para>
- <command>cookie delete</command> will set the timeout value to -1 minutes -
- deleting the cookie in the browser.
- </para>
- <para>
- <command>cookie unset</command> will remove the defined cookie in the server
- (perhaps preparatory to checking/resetting the cookie).
- </para>
+ <title>Description</title>
+ <para>
+ <command>cookie</command> gets, sets, unsets or deletes a cookie. When you
+ get a cookie, the command returns the value of the cookie,
+ or an empty string if no cookie exists.
+ </para>
+ <para>
+ <command>cookie delete</command> will set the timeout value to -1 minutes -
+ deleting the cookie in the browser.
+ </para>
+ <para>
+ <command>cookie unset</command> will remove the defined cookie in the server
+ (perhaps preparatory to checking/resetting the cookie).
+ </para>
+ <para>
+ The command has a number of switches setting a cookie attributes
+ </para>
</refsect1>
</refentry>
@@ -808,12 +844,12 @@ keyvalue_map(args) = 1 2 3 4 5</programl
variable doesn't exist, create it instead of returning an
error.
</para>
-
<note>
incr0 functionality is provided by the native <command>incr</command> in
Tcl >= 8.5, therefore this command is deprecated and kept as an
- interpreter alias only for compatibility and as such it wasn't moved to
- the ::rivet namespace. It will be removed in future versions of Rivet.
+ interpreter alias only for compatibility. As such <command>incr0</command>
+ wasn't moved to the ::rivet namespace and
+ it will be removed in future versions of Rivet.
</note>
</refsect1>
</refentry>
Modified: tcl/rivet/branches/2.1/doc/xml/directives.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/2.1/doc/xml/directives.xml?rev=1399021&r1=1399020&r2=1399021&view=diff
==============================================================================
--- tcl/rivet/branches/2.1/doc/xml/directives.xml (original)
+++ tcl/rivet/branches/2.1/doc/xml/directives.xml Tue Oct 16 22:15:57 2012
@@ -17,19 +17,16 @@
the children that actually will serve the requests coming from
the network. During this stage Apache is still running as a
single process, so this is the right place for doing
- initializations or loading packages
- that have be common to all the interpreters that will be created
- when Apache forks its child processes, even when the option
- <command>SeparateVirtualInterps</command> is set. Since this
+ initializations or loading packages. Since this
script will be running in a single process environment (from the
Apache point of view) <command>ServerInitScript</command>
- is also the right place for doing everything that must avoid
- resource concurrency among processes (e.g. the creation and
+ is also the right place for doing anything needs to avoid
+ resource concurrency among processes (e.g. the creation and
initialization of an IPC system)
</para>
</section>
<section>
- <variablelist>
+ <variablelist>
<varlistentry>
<term>
<cmdsynopsis>
@@ -128,76 +125,85 @@
</varlistentry>
<varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">ChildInitScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Script to be evaluated when each Apache child
- process is initialized. This is the recommended
- place to load modules, create global variables, open
- connections to other facilities (such as databases)
- and so on.
- </para>
- <para>
- In virtual hosts, this script is run in addition to
- any global childinitscript.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">ChildExitScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Script to be evaluated when each Apache child
- process exits. This is the logical place to clean
- up resources created in <option>ChildInitScript</option>,
- if necessary.
- </para>
- <para>
- In virtual hosts, this script is run in addition to
- any global childexitscript.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <arg choice="plain">BeforeScript</arg>
- <arg><replaceable>script</replaceable></arg>
- </cmdsynopsis>
- </term>
- <listitem>
- <para>
- Script to be evaluated before each server parsed
- (.rvt) page. This can be used to create a standard
- header, for instance. It could also be used to load
- code that you need for every page, if you don't want
- to put it in a <option>GlobalInitScript</option>
- <option>ChildInitScript</option> when you are first
- developing a web site.
- <note>
- This code is evaluated at the global level, not
- inside the request namespace where pages are
- evaluated.
- </note>
- </para>
- <para>
- In virtual hosts, this option takes precedence over
- the global setting.
- </para>
- </listitem>
- </varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">ChildInitScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Script to be evaluated when each Apache child
+ process is initialized. This is the recommended
+ place to load modules, create global variables, open
+ connections to other facilities (such as databases)
+ and so on.
+ </para>
+ <para>
+ In virtual hosts, this script is run in addition to
+ any global childinitscript.
+ When <command>SeparateVirtualInterp</command>
+ any <command>ChildInitScript</command> placed within a
+ <option><VirtualHost ...>....</VirtualHost></option>
+ will be that Virtual Host specific ininitalization
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">ChildExitScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Script to be evaluated when each Apache child
+ process exits. This is the logical place to clean
+ up resources created in <option>ChildInitScript</option>,
+ if necessary.
+ </para>
+ <para>
+ In virtual hosts, this script is run in addition to
+ any global childexitscript.
+
+ When <command>SeparateVirtualInterp</command>
+ any <command>ChildExitScript</command> placed within a
+ <option><VirtualHost ...>....</VirtualHost></option>
+ will be that Virtual Host specific exit handler
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">BeforeScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Script to be evaluated before each server parsed
+ (.rvt) page. This can be used to create a standard
+ header, for instance. It could also be used to load
+ code that you need for every page, if you don't want
+ to put it in a <option>GlobalInitScript</option>
+ <option>ChildInitScript</option> when you are first
+ developing a web site.
+ <note>
+ This code is evaluated at the global level, not
+ inside the request namespace where pages are
+ evaluated.
+ </note>
+ </para>
+ <para>
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term>
Modified: tcl/rivet/branches/2.1/doc/xml/examples.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/2.1/doc/xml/examples.xml?rev=1399021&r1=1399020&r2=1399021&view=diff
==============================================================================
--- tcl/rivet/branches/2.1/doc/xml/examples.xml (original)
+++ tcl/rivet/branches/2.1/doc/xml/examples.xml Tue Oct 16 22:15:57 2012
@@ -1,5 +1,6 @@
<section id="examples">
<title>Examples and Usage</title>
+
<para>
Some examples of Rivet usage follow. Some prior Tcl knowledge
is assumed. If you don't know much Tcl, don't worry, it's easy,
@@ -8,7 +9,7 @@
<link linkend="websites">web sites</link> section and have a look.
</para>
- <example id="hello world">
+ <example id="hello_world">
<title>Hello World</title>
<para>
As with any tool, it's always nice to see something work, so
Modified: tcl/rivet/branches/2.1/doc/xml/install.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/2.1/doc/xml/install.xml?rev=1399021&r1=1399020&r2=1399021&view=diff
==============================================================================
--- tcl/rivet/branches/2.1/doc/xml/install.xml (original)
+++ tcl/rivet/branches/2.1/doc/xml/install.xml Tue Oct 16 22:15:57 2012
@@ -1,19 +1,25 @@
<section id="installation">
<title>Apache Rivet Installation</title>
<procedure>
+ <para>
+ Rivet 2.1 runs with the Apache 2.2.x and 2.4.x HTTP web server.
+ It is known to build and run on various Linux distributions
+ (Debian & Ubuntu, Redhat, SuSE and CentOS), FreeBSD and OpenBSD. For some
+ of these Unix-like operative systems
+ <ulink url="http://tcl.apache.org/rivet/static/download.html">binary packages</ulink>
+ are already available for download.
+ </para>
<para>
- Check your OS website for a binary package of Apache Rivet.
- Rivet 2.1 runs with the Apache Apache 2.2.x and 2.4.x server.
- It is known to run on various Linux distributions
- (Debian & Ubuntu, Redhat, SuSE and CentOS), FreeBSD and OpenBSD.
- Currently there is no way to run Apache Rivet on Windows© with Apache 2.2, since
- no <ulink url="http://httpd.apache.org/docs/2.2/mpm.html">Multi-Processing Module</ulink>
- other than
- <ulink url="http://httpd.apache.org/docs/2.2/mod/prefork.html">prefork</ulink> is supported.
- Efforts are under way to extend the support to the
- <ulink url="http://httpd.apache.org/docs/2.2/mod/worker.html">worker</ulink> MPM, which could
- open the possibility to run Apache Rivet also with the
- <ulink url="http://httpd.apache.org/docs/2.2/mod/mpm_winnt.html">winnt</ulink> MPM.
+ Currently there is no way to run Apache Rivet 2.1 on Windows© because
+ Rivet currently requires the
+ <ulink url="http://httpd.apache.org/docs/2.2/mod/prefork.html">prefork</ulink>, which
+ is supported only on Unix/Linux systems. Efforts are under way to extend the support to the
+ <ulink url="http://httpd.apache.org/docs/2.2/mod/worker.html">worker</ulink>
+ and the
+ <ulink url="http://httpd.apache.org/docs/2.2/mod/mpm_winnt.html">winnt</ulink> MPMs.
+ Check our
+ <ulink url="http://tcl.apache.org/rivet/static/about.html">development mailing list</ulink>
+ for the latests updates about Rivet development
</para>
<para>
If you need to compile Apache Rivet yourself this is the procedure to follow
@@ -21,27 +27,30 @@
<step performance="required">
<title>Install Tcl</title>
<para>
- To build Rivet, you will need to install the shell (<command>tclsh</command>),
- the development headers and the libraries from Tcl (≥8.5.10). You will tell Rivet
- build scripts where Tcl is located via the <option>--with-tcl</option> option to
- <command>configure</command> (see below).
+ Installing Rivet is about endowing the Apache HTTP webserver with the ability
+ of running scripts written with the Tcl programming language.
+ Therefore the
+ <ulink url="http://www.tcl.tk/">Tcl</ulink>
+ shell (<command>tclsh</command>), its runtime and
+ development libraries (≥8.5.10) have to be installed. Building Rivet you will
+ have to tell the scripts where the Tcl libraries are located via the
+ <option>--with-tcl</option> option to <command>configure</command> (see below).
</para>
- </step>
- <step>
+ </step>
+ <step>
<title>Get Rivet</title>
<para>
Download the sources at <ulink url="http://tcl.apache.org/rivet/download.html"/>.
</para>
- </step>
- <step performance="optional">
+ </step>
+ <step performance="optional">
<title>Get and Install Apache Sources</title>
<para>
- Rivet needs some Apache include (.h) files in order to build. The easiest way
- to get them is to download the source code of the Apache web server, although some systems
- (Debian GNU/Linux for example) make it possible to install only the headers and other
- development files. If you intend to build Rivet statically (compiled into the Apache web
- server instead of loaded dynamically), you definitely need the sources.
- We recommend that you build Rivet as a loadable shared library, for maximum flexibility,
+ Rivet needs some of the include (.h) files shipped with the webserver source code.
+ The easiest way to get them is to download the Apache source.
+ If can build Rivet either statically (compiled into the Apache web
+ server instead of loaded dynamically) or dynamically (as a loadable shared library).
+ We recommend that you build Rivet as a shared library, for maximum flexibility,
meaning that you also build Apache to be able to load modules. Other than that,
the default Apache install is fine. We will tell Rivet where it is located via the
<option>--with-apxs</option> option to <command>configure</command> (see below).
Modified: tcl/rivet/branches/2.1/doc/xml/request.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/2.1/doc/xml/request.xml?rev=1399021&r1=1399020&r2=1399021&view=diff
==============================================================================
--- tcl/rivet/branches/2.1/doc/xml/request.xml (original)
+++ tcl/rivet/branches/2.1/doc/xml/request.xml Tue Oct 16 22:15:57 2012
@@ -3,71 +3,79 @@
<simplesect>
<title>Apache Child Process Lifecycle</title>
- <para>
+ <para>
Apache Rivet delegates to the <ulink url="">Multi-Processing Module (MPM)</ulink>
the task of managing the agents responding to network requests.
An MPM is responsible for creating such agents during the start-up,
and is in charge for terminating existing ones and recreating new
agents when the workload is requiring it.
- </para>
- <para>
+ </para>
+ <para>
Apache Rivet is currently supporting only the
- <ulink url="http://httpd.apache.org/docs/2.2/mod/prefork.html">prefork</ulink> MPM which creates full
- fledge child processes as independent agents responding to network requests.
+ <ulink url="http://httpd.apache.org/docs/2.2/mod/prefork.html">prefork</ulink>
+ MPM which creates full fledged child processes as independent agents
+ responding to network requests.
Efforts are under way to extend the support to
- the <ulink url="http://httpd.apache.org/docs/2.2/mod/worker.html">worker</ulink> MPM, a hybrid model where forked
- child processes in turn create threads as real network agents. If we can achieve this the goal
- would open the possibility of supporting also the Windows© specific
- <ulink url="http://httpd.apache.org/docs/2.2/mod/mpm_winnt.html">winnt</ulink> MPM, where
- a single process creates and manages a large number of thread agents.
- </para>
- <para>
- Configuration parameters about this critical point can be read in the
- <ulink url="http://httpd.apache.org/docs/2.2/misc/perf-tuning.html">Apache
- documentation</ulink>.
+ the <ulink url="http://httpd.apache.org/docs/2.2/mod/worker.html">worker</ulink> MPM,
+ a hybrid model where forked child processes in turn create threads as real
+ network agents. If we can achieve this the goal would open the possibility of
+ supporting also the Windows© specific
+ <ulink url="http://httpd.apache.org/docs/2.2/mod/mpm_winnt.html">winnt</ulink> MPM,
+ where a single process creates and manages a large number of thread agents.
+ </para>
+ <para>
+ Configuration parameters about this critical point can be read in the
+ <ulink url="http://httpd.apache.org/docs/2.2/misc/perf-tuning.html">Apache
+ documentation</ulink>.
</para>
<para>
- There are 4 stages in the lifetime of an Apache webserver that are relevant
- to Rivet:
+ There are 4 stages in the lifetime of an Apache webserver that are relevant
+ to Rivet:
</para>
<orderedlist>
<listitem>
<bridgehead>Single Process Initialization</bridgehead>
<para>
- Apaches starts up as a single process and you can drop in the configuration
- a script to be run during this stage through the <command>ServerInitScript</command>
- directive. Variables, arrays or dictionaries set up during this stage will be
- replicated in a child process intepreter at high speed, since a fork() call
- involves only in memory copy of sections of a process address space. Thus
- <command>ServerInitScript</command>
+ Apaches starts up as a single process. During this stage Apache performs
+ various preliminary tasks including reading and parsing the configuration.
+ After the configuration has been read Rivet sets up some internal resources
+ and if a Tcl script is set as argument of a <command>ServerInitScript</command> directive
+ the script is executed.
+ Variables, arrays or dictionaries created during the execution of this script
+ will be preserved and later replicated in the child process intepreters,
+ since the prefork MPM creates new child processes with a fork() system call (which
+ involves only in memory copy of sections of a process address space). Thus
+ <command>ServerInitScript</command>
is a good place to do global initialization that doesn't involve
creation of private data. Example of tasks that can be done
in this context are importing namespace commands and loading packages
providing code of general interest for every application to
- be served.
+ be served. Also IPC methods can be initialized in this stage.
</para>
</listitem>
<listitem>
<bridgehead>Child Process Initialization</bridgehead>
<para>
- Right after the webserver has forked the child processes
- there is a chance to perform specific initialization of their interpreters.
- This is the stage where most likely you want to open I/O channels,
- database connections or any other resource that has to be private to an
- interpreter. When the option <command>SeparateVirtualInterps</command> is
- turned off child processes will have a single interpreter regardless
- the number of virtual hosts for which a configuration block
- is defined. This interpreter will have a <command>GlobalInitScript</command>
- as initialization.
+ Right after the webserver has forked its child processes
+ there is a chance to perform specific initialization of their Tcl interpreters.
+ This is the stage where most likely you want to open I/O channels,
+ database connections or any other resource that has to be private to an
+ interpreter. When the option <command>SeparateVirtualInterps</command> is
+ turned off child processes will have a single interpreter regardless
+ the number of virtual hosts configured. The
+ <command>GlobalInitScript</command> is the configuration script
+ the child process will run once before getting ready to
+ serve requests
</para>
<para>
When <command>SeparateVirtualInterps</command> is turned on
- each configured virtual host will have its own slave interpreter.
- <command>ChildInitScript</command> is the directive to be
+ each configured virtual host will have its own slave interpreter which
+ can will run the <command>ChildInitScript</command> directive as
+ initialization script. The
+ <command>ChildInitScript</command> has to be
placed within a <VirtualHost...>...</VirtualHost ...>
- stanza to have a special initialization of an interpreter bound to
- a certain virtual host. This scenario of interpreter
- separation is extremely useful to
+ stanza to associate a script to a specific virtual host initialization.
+ This scenario of interpreter separation is extremely useful to
prevent resource conflicts when different virtual hosts are
serving different web applications.
</para>
@@ -81,49 +89,49 @@
<listitem>
<bridgehead>Request Processing and Content Generation</bridgehead>
<para>
- After a child has been initialized it's ready to serve requests.
- A child process' lifetime is almost entirely spent in this phase, waiting
- for connections and responding to requests. At every request the URL
- goes through filter processing and, in case, rewritten
- (mod_rewrite, Alias directives, etc).
- Parameter values encoded in the request are made available to the
- environment and finally the script encoded in the URL is run.
- The developer can tell Rivet if optionally the execution has to
- be preceded by a <command>BeforeScript</command> and followed by an
- <command>AfterScript</command>. The real script mod_rivet will
- execute is the result of the concatenation of the
- <command>BeforeScript</command>,
- the script encoded in the URL and the <command>AfterScript</command>.
- Thus the whole ensemble of code that makes up a web application might
- be running within the same "before" and "after" scripts to which
- the programmer can devolve tasks common to every
- page of an application.
- </para>
- </listitem>
- <listitem>
- <bridgehead>Child Process Exit</bridgehead>
- <para>
- If no error condition forces the child process to a premature exit, his
- life is determined by the Apache configuration parameters. To reduce
- the effects of memory leaks in buggy applications the Apache webserver
- forces a child process to exit after a
- certain number of requests served. A child process gets replaced
- with a brand new one if the workload of webserver requires so.
- Before the process quits an exit handler can be run
- to do some housekeeping, just in case something the could have been
- left behind has to be cleaned up. Like the initialization scripts
- <command>ChildExitScript</command> too is a "one shot" script.
- </para>
- <para>
- The Tcl <command>exit</command> command forces an interpreter to
- quit, thus removing the ability of the process embedding it
- to run more Tcl scripts. The child process then is forced
- to exit and be replaced by a new one when the workload demands it.
- This operation implies the <command>ChildExitScript</command> be
- run before the interpreter is actually deleted.
- </para>
- </listitem>
- </orderedlist>
+ After a child has been initialized it's ready to serve requests.
+ A child process' lifetime is almost entirely spent in this phase, waiting
+ for connections and responding to requests. At every request the URL
+ goes through filter processing and, in case, rewritten
+ (mod_rewrite, Alias directives, etc).
+ Parameter values encoded in the request are made available to the
+ environment and finally the script encoded in the URL is run.
+ The developer can tell Rivet if optionally the execution has to
+ be preceded by a <command>BeforeScript</command> and followed by an
+ <command>AfterScript</command>. The real script mod_rivet will
+ execute is the result of the concatenation of the
+ <command>BeforeScript</command>,
+ the script encoded in the URL and the <command>AfterScript</command>.
+ Thus the whole ensemble of code that makes up a web application might
+ be running within the same "before" and "after" scripts to which
+ the programmer can devolve tasks common to every
+ page of an application.
+ </para>
+ </listitem>
+ <listitem>
+ <bridgehead>Child Process Exit</bridgehead>
+ <para>
+ If no error condition forces the child process to a premature exit, his
+ life is determined by the Apache configuration parameters. To reduce
+ the effects of memory leaks in buggy applications the Apache webserver
+ forces a child process to exit after a
+ certain number of requests served. A child process gets replaced
+ with a brand new one if the workload of webserver requires so.
+ Before the process quits an exit handler can be run
+ to do some housekeeping, just in case something the could have been
+ left behind has to be cleaned up. Like the initialization scripts
+ <command>ChildExitScript</command> too is a "one shot" script.
+ </para>
+ <para>
+ The Tcl <command>exit</command> command forces an interpreter to
+ quit, thus removing the ability of the process embedding it
+ to run more Tcl scripts. The child process then is forced
+ to exit and be replaced by a new one when the workload demands it.
+ This operation implies the <command>ChildExitScript</command> be
+ run before the interpreter is actually deleted.
+ </para>
+ </listitem>
+ </orderedlist>
</simplesect>
<simplesect>
<title>Apache Rivet Error and Exception Scripts Directives</title>
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-cvs-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-cvs-help@tcl.apache.org