You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tcl.apache.org by mx...@apache.org on 2019/08/22 02:55:29 UTC
[tcl-rivet] 01/03: documenting directive SingleThreadExit
This is an automated email from the ASF dual-hosted git repository.
mxmanghi pushed a commit to branch quattuor
in repository https://gitbox.apache.org/repos/asf/tcl-rivet.git
commit dc2e2cdcca4e2c27c2e9c8d2853412b77dba38e6
Author: Massimo Manghi <mx...@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 1f48460..8f4a07f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,6 @@
+2019-08-05 Massimo Manghi <mx...@apache.org>
+ * doc/xml/directives.xml: Documenting SingleThreadExit directive
+
2019-06-30 Massimo Manghi <mx...@apache.org>
* src/mod_rivet_ng/rivet_worker_mpm.c: Removed unnecessary access to thread private data
in WorkerBridge_Finalize
diff --git a/doc/rivet.xml b/doc/rivet.xml
index 4aa257f..df513fe 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 2772fab..c977320 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-unsubscribe@tcl.apache.org
For additional commands, e-mail: commits-help@tcl.apache.org