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 2011/03/24 01:45:09 UTC
svn commit: r1084818 - in /tcl/rivet/trunk/doc: rivet.xml xml/commands.xml
xml/request.xml
Author: mxmanghi
Date: Thu Mar 24 00:45:08 2011
New Revision: 1084818
URL: http://svn.apache.org/viewvc?rev=1084818&view=rev
Log:
apache configuration and process lifecycle explained in request.xml
Added:
tcl/rivet/trunk/doc/xml/request.xml
Modified:
tcl/rivet/trunk/doc/rivet.xml
tcl/rivet/trunk/doc/xml/commands.xml
Modified: tcl/rivet/trunk/doc/rivet.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/rivet.xml?rev=1084818&r1=1084817&r2=1084818&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/rivet.xml (original)
+++ tcl/rivet/trunk/doc/rivet.xml Thu Mar 24 00:45:08 2011
@@ -18,12 +18,13 @@
<!ENTITY packages.xml SYSTEM "xml/packages.xml" >
<!ENTITY dio.xml SYSTEM "xml/dio.xml" >
<!ENTITY diodisplay.xml SYSTEM "xml/diodisplay.xml" >
- <!ENTITY session.xml SYSTEM "xml/session.xml" >
- <!ENTITY form.xml SYSTEM "xml/form.xml" >
- <!ENTITY calendar.xml SYSTEM "xml/calendar.xml" >
- <!ENTITY help.xml SYSTEM "xml/help.xml" >
- <!ENTITY internals.xml SYSTEM "xml/internals.xml" >
- <!ENTITY upgrade.xml SYSTEM "xml/upgrade.xml" >
+ <!ENTITY session.xml SYSTEM "xml/session.xml" >
+ <!ENTITY form.xml SYSTEM "xml/form.xml" >
+ <!ENTITY calendar.xml SYSTEM "xml/calendar.xml" >
+ <!ENTITY help.xml SYSTEM "xml/help.xml" >
+ <!ENTITY internals.xml SYSTEM "xml/internals.xml" >
+ <!ENTITY upgrade.xml SYSTEM "xml/upgrade.xml" >
+ <!ENTITY request.xml SYSTEM "xml/request.xml" >
]>
<!--
@@ -86,6 +87,9 @@
<!-- Installation -->
&install.xml;
+
+ <!-- Configuration -->
+ &request.xml;
<!-- Directives -->
&directives.xml;
Modified: tcl/rivet/trunk/doc/xml/commands.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/xml/commands.xml?rev=1084818&r1=1084817&r2=1084818&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/xml/commands.xml (original)
+++ tcl/rivet/trunk/doc/xml/commands.xml Thu Mar 24 00:45:08 2011
@@ -118,13 +118,13 @@
<varlistentry>
<term>
<cmdsynopsis>
- <command>var</command>
- <arg choice="plain">number</arg>
+ <command>var</command>
+ <arg choice="plain">number</arg>
</cmdsynopsis>
</term>
<listitem>
<para>
- Returns the number of variables.
+ Returns the number of variables.
</para>
</listitem>
</varlistentry>
@@ -803,7 +803,7 @@
<refnamediv>
<refname>abort_page</refname>
<refpurpose>
- Stops outputing data to web page, similar in
+ Stops outputting data to web page, similar in
purpose to PHP's <command>die</command> command.
</refpurpose>
</refnamediv>
Added: tcl/rivet/trunk/doc/xml/request.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/xml/request.xml?rev=1084818&view=auto
==============================================================================
--- tcl/rivet/trunk/doc/xml/request.xml (added)
+++ tcl/rivet/trunk/doc/xml/request.xml Thu Mar 24 00:45:08 2011
@@ -0,0 +1,132 @@
+<section id="request">
+ <title>Apache Child Processes Lifecycle and Request Processing</title>
+
+ <simplesect>
+ <title>Apache Child Process Lifecycle</title>
+ <para>
+ HTTP requests are served by child processes spwaned by the
+ webserver at start up. The number of child processes created
+ can be controlled in the Apache configuration and the optimum in the choice
+ of this number largely depends on the webserver workload and on the system
+ resources available. See
+ <ulink href="http://httpd.apache.org/docs/2.2/misc/perf-tuning.html">Apache
+ documentation</ulink> for further reading about this crucial point.
+ Each of the child process is set up to respond to requests
+ that will come from the network accordingly to the configuration
+ parameters. If your webserver has been properly configured you will have Tcl
+ scripts being run and Rivet templates being parsed and executed after
+ specific requests have been sent to the server. This is going to be the
+ time when your web application will be doing much of its work
+ creating content to be sent as output to the client.
+ </para>
+ <para>
+ There are 4 stages in the life of an Apache webserver that are relevant
+ to Rivet:
+ </para>
+ <orderedlist>
+ <listitem>
+ <bridgehead>Single Process Initialization</bridgehead>
+ <para>
+ After the configuration has been read and parsed but before Apache
+ spawns the child processes the webserver is still
+ a single process application. In this phase
+ <command>ServerInitScript</command>
+ can be specified to run a Tcl right after Rivet
+ has created and initialized a master interpreter, a Tcl interpreter
+ object from which child processes interpreters will be created by
+ copy. The master interpreter will be kept in the Apache's parent
+ process and also subsequent child processes interpreters will inherit
+ the status of the parent process interpreter.
+ </para>
+ </listitem>
+ <listitem>
+ <bridgehead>Child Process Initialization</bridgehead>
+ <para>
+ Right after the webserver has created the child processes that are
+ to become the real "servers" responding to requests. In this phase there is
+ a chance to perform specific initialization for the each child process
+ such as opening I/O channels or database connections. If the option
+ <command>SeparateVirtualInterps</command> is turned off child processes
+ will have a single interpreter to serve requests.
+ <command>GlobalInitScript</command>
+ is the directive to tell interpreter the Tcl code for the initialization.
+ This is right place where data and resources that have to be private
+ to the process can be created and initialized (e.g. I/O channels and
+ DBMS connectors).
+ </para>
+ <para>
+ When <command>SeparateVirtualInterps</command> is turned on
+ each configured virtual host will have its own interpreter.
+ <command>ChildInitScript</command> is the directive to be
+ placed withing a <VirtualHost ...> that will prepare
+ the specific environment.
+ </para>
+ </listitem>
+ <listitem>
+ <bridgehead>Request Processing and Content Generation</bridgehead>
+ <para>
+ After a child has been initialized it becomes ready to serve request.
+ The child process life is spent almost completely in this phase, waiting
+ for connections and responding to requests. At every request the URL will
+ go the usual processing and (in case rewritten by metadata manipulators),
+ variables passed to the webserver will be made available in the
+ environment and finally the script coded in the URL will be run.
+ The script execution can be preceded by a configured
+ <command>BeforeScript</command> and followed by a
+ <command>AfterScript</command>. Actually the real script executed is
+ formed by the concatenation of the <command>BeforeScript</command> ,
+ the script selected by the URL and by the <command>AfterScript</command>.
+ Thus it is possible that the whole collection of scripts that make up a
+ web application will have the same "before" and "after" scripts to which
+ the programmer can devolve tasks common to every page
+ (they can access to request variables and environment so that
+ they can modulate their flow and vary their execution depending on
+ specific parameters)
+ </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 configuration parameters. To avoid problems with
+ buggy applications the Apache webserver forces a child process to exit after a
+ certain number of requests served and replaces it with a brand new
+ child process. 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> is a "one shot" script.
+ </para>
+ </listitem>
+ </orderedlist>
+ </simplesect>
+ <simplesect>
+ <title>Apache Rivet Error and Exception Scripts Directives</title>
+ <para>
+ Rivet is highly configurable and each of the stages can be exploited
+ to control a web application. Not only the orderly sequence of stages
+ in the child process cycle can be controlled with Tcl scripts, but also
+ Tcl error conditions or abnormal conditions that can take place during
+ the content generation can be caught and handled with specific scripts
+ </para>
+ <para>
+ For instance Tcl errors will by default result in the printing of
+ a backtrace that usually shows the code fragment where the error occurred.
+ Rivet configuration can set up scripts to trap these errors and instead run
+ an <command>ErrorScript</command> to handle the error and conceal details
+ of the code that usually have no relevant information for the end user and
+ can expose details of the code that ought to remain private.
+ </para>
+ <para>
+ In other cases an unmanageable conditions might take place in the data and
+ this could demand a sudden interruption of the page request. These abort
+ conditions can be fired by the <xref linkend="abort_page"/> command which
+ in turn fires the execution of an <command>AbortScript</command> to handle
+ the abnormal execution.
+ </para>
+ </simplesect>
+ <simplesect>
+ <title>Handler Tcl Namespaces</title>
+ <para>
+ </para>
+ </simplesect>
+</section>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-cvs-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-cvs-help@tcl.apache.org