This is an automated email from the ASF dual-hosted git repository.
mxmanghi pushed a commit to branch single-thread-exit
in repository https://gitbox.apache.org/repos/asf/tcl-rivet.git
The following commit(s) were added to refs/heads/single-thread-exit by this
push:
new 47e58cd documenting directive SingleThreadExit
47e58cd is described below
commit 47e58cd8440de46160d6c2ac64ea1683c41469cd
Author: Massimo Manghi <mxman...@apache.org>
AuthorDate: Tue Aug 6 00:40:42 2019 +0200
documenting directive SingleThreadExit
---
ChangeLog | 3 +++
doc/rivet.xml | 1 +
doc/rivet.xml.in | 1 +
doc/xml/commands.xml | 52 ++++++++++++++++++++++++++++----------------------
doc/xml/directives.xml | 25 +++++++++++++++++++++++-
5 files changed, 58 insertions(+), 24 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 5bbfeae..9a19f9f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,6 @@
+2019-08-05 Massimo Manghi <mxman...@apache.org>
+ * doc/xml/directives.xml: Documenting SingleThreadExit directive
+
2019-06-25 Massimo Manghi <mxman...@apache.org>
* : Single thread exit implementation for mod_rivet 3.2
* src/mod_rivet_ng/rivet_[.*]_mpm.c: further simplified code by removing
diff --git a/doc/rivet.xml b/doc/rivet.xml
index a4fe95e..dbcf947 100644
--- a/doc/rivet.xml
+++ b/doc/rivet.xml
@@ -41,6 +41,7 @@
<!ENTITY version2-generic "2.x" >
<!ENTITY version30 "3.0" >
<!ENTITY version31 "3.1" >
+ <!ENTITY version32 "3.2" >
<!ENTITY tcltk-url "http://www.tcl.tk/"; >
<!ENTITY apache-url "http://httpd.apache.org"; >
<!ENTITY apache-apr "http://apr.apache.org/"; >
diff --git a/doc/rivet.xml.in b/doc/rivet.xml.in
index 4cda7bb..825e1ee 100644
--- a/doc/rivet.xml.in
+++ b/doc/rivet.xml.in
@@ -41,6 +41,7 @@
<!ENTITY version2-generic "2.x" >
<!ENTITY version30 "3.0" >
<!ENTITY version31 "3.1" >
+ <!ENTITY version32 "3.2" >
<!ENTITY tcltk-url "http://www.tcl.tk/"; >
<!ENTITY apache-url "http://httpd.apache.org"; >
<!ENTITY apache-apr "http://apr.apache.org/"; >
diff --git a/doc/xml/commands.xml b/doc/xml/commands.xml
index a8fc1f0..24a2484 100644
--- a/doc/xml/commands.xml
+++ b/doc/xml/commands.xml
@@ -353,19 +353,20 @@
<refsect1>
<title>Description</title>
<para>
- <command>::rivet::catch</command> wraps the core
language's same command adding some
- extra error handling needed by mod_rivet design.
- The rationale for Rivet to have its own
<command>::rivet::catch</command> reads as follows:
- within mod_rivet a script execution can be interrupted by either
calling
- <command>::rivet::exit</command>(deprecated) or
<command>::rivet::abort_page</command>. These commands
- implement a simple internal exception mechanism by
+ <command>::rivet::catch</command> wraps the core
language <command>catch</command>
+ command adding some extra error handling needed by
mod_rivet design.
+ The rationale for Rivet to have its own
<command>::rivet::catch</command> reads
+ as follows: within mod_rivet a script execution can be
interrupted by either calling
+ <command>::rivet::exit</command>(deprecated) or
<command>::rivet::abort_page</command>.
+ These commands implement a simple internal exception
mechanism by
returning a special error code so that execution is in turn handed
down to the
- <command>AbortScript</command> and eventually to
<command>AfterEveryScript</command> (if any of them is
- defined). Any code calling one of these commands which runs under
control of the
- <command>::catch</command> command would need to do this chore
itself, checking the error info and in case
- throw the error again if it had been originated by one of
mod_rivet's exceptions calls.
- This is what <command>::rivet::catch</command> does hiding the
implementation
- details provide a better and more compatibile way to handle this
condition.
+ <command>AbortScript</command> and eventually to
<command>AfterEveryScript</command>
+ (if any of them is defined). Any code calling one of these
commands which runs under
+ control of the <command>::catch</command> command would need to do
this chore itself,
+ checking the error info and in case throw the error again if it
had been originated
+ by one of mod_rivet's exceptions calls. This is what
<command>::rivet::catch</command>
+ does hiding the implementation details provide a better and more
compatibile way to
+ handle this condition.
</para>
<note>
@@ -625,8 +626,9 @@
Replaces Tcl's <command>exit</command> core
command. <command>::rivet::exit</command>
interrupts execution of the current script and
passes execution to AbortScript if
such script is set. After AbortScript has
finished and request processing completed
- the child process is forced to exit by calling
Tcl_Exit producing the same final
- effect of the core command. During an
<command>AbortScript</command> execution the
+ the child process is forced to exit by
eventually calling Tcl_Exit producing the same final
+ effect of the core command.
+ During an <command>AbortScript</command>
execution the
exit condition can be detected
<programlisting>if
{[<command>::rivet::abort_page -exiting</command>]} {
...handle exit condition
@@ -641,13 +643,17 @@
<programlisting>[::rivet::abort_code]
<== return_code <arg>code</arg> error_code exit</programlisting>
<para>
- We support this command in order to have a
gentle way to terminate a request processing
- before actually exit the child process and
avoid an abrupt interruption of a request that
- might leave an application in a inconsistent
state. In some cases <command>::rivet::exit</command>
- could be the only way to exit a process and
force the Apache HTTP web server to start
- a fresh one. Moreover the core
<command>exit</command> could be called from third parties
- software and you may not be aware of it. We
thus decided to trap this command and give it
- the most gentle behavior still preserving its
basic purpose.
+ Rivet's specific implementation prevents any
abrupt process termination
+ that otherwise the <command>exit</command>
command would bring about deferring
+ the call to Tcl_Exit to a later stage when the
request processing has finished.
+ This is always true if the mod_rivet runs the
prefork bridge. The behavior with
+ the worker bridge depends on the
<command>SingleThreadExit</command> configuration
+ directive. By default all the threads of a
single process are requested to exit
+ before the child process exits. Starting with
version &version32;
+ by setting the
<command>SingleThreadExit</command> option directive
+ calling <command>::rivet::exit</command> causes
a single thread termination.
+ Though always accepted this directive is
meaningful only if used with the worker
+ or lazy bridges.
</para>
<note>
Nonetheless we discourage the programmer to use
such command, and suggest to focus on proper
@@ -656,12 +662,12 @@
MaxRequests parameter in the
<ulink
url="https://httpd.apache.org/docs/2.4/mod/prefork.html";>prefork MPM
documentation</ulink>
or the
- <ulink
url="http://httpd.apache.org/docs/2.0/mod/mpm_common.html#maxrequestsperchild";>MaxRequestsPerChild</ulink>
+ <ulink
url="http://httpd.apache.org/docs/2.4/mod/mpm_common.html#maxrequestsperchild";>MaxRequestsPerChild</ulink>
configuration parameter
</note>
</refsect1>
</refentry>
-
+
<refentry id="headers">
<refnamediv>
<refname>headers</refname>
diff --git a/doc/xml/directives.xml b/doc/xml/directives.xml
index fcd6407..500fa25 100644
--- a/doc/xml/directives.xml
+++ b/doc/xml/directives.xml
@@ -72,7 +72,8 @@
<tr><td>RequestHandler</td><td></td><td></td><td>X</td><td>X</td><td></td></tr>
<tr><td>SeparateChannels</td><td></td><td></td><td>X</td><td></td><td>global
setting</td></tr>
<tr><td>SeparateVirtualInterps</td><td></td><td></td><td>X</td><td></td><td>global
setting</td></tr>
-
<tr><td>ServerInitScript</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+
<tr><td>ServerInitScript</td><td></td><td></td><td>X</td><td></td><td></td></tr>
+
<tr><td>SingleThreadExit</td><td></td><td></td><td>X</td><td></td><td>global
setting only</td></tr>
<tr><td>UploadDirectory</td><td></td><td>X</td><td>X</td><td>X</td><td></td></tr>
<tr><td>UploadFilesToVar</td><td></td><td></td><td>X</td><td></td><td></td></tr>
<tr><td>UploadMaxSize</td><td></td><td></td><td>X</td><td>X</td><td></td></tr>
@@ -484,7 +485,29 @@
any subsequent Tcl interpreters created
by fork calls as each
of them are clones of the master
interpreter.
</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg
choice="plain">SingleThreadExit</arg>
+ <group
choice="req"><arg>yes</arg><arg>no</arg></group>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Rivet shadows the Tcl
<command>exit</command> command with the
+ <command>::rivet::exit</command> in
order to
+ prevent abrupt interruption of
execution of a child process when
+ multiple thread are running. By default
the worker bridge notifies
+ all the threads running Tcl
interpreters to exit before calling Tcl_Exit.
+ If this option is set a single thread
terminates executing any ChildExitScript
+ and eventually it's replaced
accordingly to
+ the thread management policy
implemented by the bridge.
+ With the prefork bridge this options
reproduces the ordinary
+ <command>exit</command> command
behavior.
+ </para>
</listitem>
</varlistentry>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@tcl.apache.org
For additional commands, e-mail: commits-h...@tcl.apache.org
