You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by co...@apache.org on 2015/12/28 19:24:39 UTC
svn commit: r1721974 - in /httpd/httpd/branches/2.4.x/docs/manual/developer:
filters.html.en filters.xml hooks.html.en hooks.xml index.html.en index.xml
request.html.en request.xml
Author: covener
Date: Mon Dec 28 18:24:39 2015
New Revision: 1721974
URL: http://svn.apache.org/viewvc?rev=1721974&view=rev
Log:
Merge r1721973 from trunk:
PR58761: developer doc improvements.
Submitted By: Luca Toscano
Modified:
httpd/httpd/branches/2.4.x/docs/manual/developer/filters.html.en
httpd/httpd/branches/2.4.x/docs/manual/developer/filters.xml
httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.html.en
httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.xml
httpd/httpd/branches/2.4.x/docs/manual/developer/index.html.en
httpd/httpd/branches/2.4.x/docs/manual/developer/index.xml
httpd/httpd/branches/2.4.x/docs/manual/developer/request.html.en
httpd/httpd/branches/2.4.x/docs/manual/developer/request.xml
Modified: httpd/httpd/branches/2.4.x/docs/manual/developer/filters.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/developer/filters.html.en?rev=1721974&r1=1721973&r2=1721974&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/developer/filters.html.en (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/developer/filters.html.en Mon Dec 28 18:24:39 2015
@@ -105,12 +105,14 @@
<p>This is actually rather simple in theory, but the code is
complex. First of all, it is important that everybody realize that
there are three filter lists for each request, but they are all
- concatenated together. So, the first list is
- <code>r->output_filters</code>, then <code>r->proto_output_filters</code>,
- and finally <code>r->connection->output_filters</code>. These correspond
- to the <code>RESOURCE</code>, <code>PROTOCOL</code>, and
- <code>CONNECTION</code> filters respectively. The problem previously, was
- that we used a singly linked list to create the filter stack, and we
+ concatenated together:</p>
+ <ul>
+ <li><code>r->output_filters</code> (corresponds to RESOURCE)</li>
+ <li><code>r->proto_output_filters</code> (corresponds to PROTOCOL)</li>
+ <li><code>r->connection->output_filters</code> (corresponds to CONNECTION)</li>
+ </ul>
+
+ <p>The problem previously, was that we used a singly linked list to create the filter stack, and we
started from the "correct" location. This means that if I had a
<code>RESOURCE</code> filter on the stack, and I added a
<code>CONNECTION</code> filter, the <code>CONNECTION</code> filter would
Modified: httpd/httpd/branches/2.4.x/docs/manual/developer/filters.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/developer/filters.xml?rev=1721974&r1=1721973&r2=1721974&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/developer/filters.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/developer/filters.xml Mon Dec 28 18:24:39 2015
@@ -99,12 +99,14 @@
<p>This is actually rather simple in theory, but the code is
complex. First of all, it is important that everybody realize that
there are three filter lists for each request, but they are all
- concatenated together. So, the first list is
- <code>r->output_filters</code>, then <code>r->proto_output_filters</code>,
- and finally <code>r->connection->output_filters</code>. These correspond
- to the <code>RESOURCE</code>, <code>PROTOCOL</code>, and
- <code>CONNECTION</code> filters respectively. The problem previously, was
- that we used a singly linked list to create the filter stack, and we
+ concatenated together:</p>
+ <ul>
+ <li><code>r->output_filters</code> (corresponds to RESOURCE)</li>
+ <li><code>r->proto_output_filters</code> (corresponds to PROTOCOL)</li>
+ <li><code>r->connection->output_filters</code> (corresponds to CONNECTION)</li>
+ </ul>
+
+ <p>The problem previously, was that we used a singly linked list to create the filter stack, and we
started from the "correct" location. This means that if I had a
<code>RESOURCE</code> filter on the stack, and I added a
<code>CONNECTION</code> filter, the <code>CONNECTION</code> filter would
Modified: httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.html.en?rev=1721974&r1=1721973&r2=1721974&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.html.en (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.html.en Mon Dec 28 18:24:39 2015
@@ -36,11 +36,29 @@
Modules can provide functions that are called, and specify when
they get called in comparison to other modules.</p>
</div>
-<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#create">Creating a hook function</a></li>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#corehooks">Core Hooks</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#create">Creating a hook function</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#hooking">Hooking the hook</a></li>
</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
+<h2><a name="corehooks" id="corehooks">Core Hooks</a></h2>
+ <p>The httpd's core modules offer a predefinined list of hooks
+ used during the standard <a href="./request.html">request processing</a>
+ phase. Creating a new hook will expose a function that
+ implements it (see sections below) but it is essential to undestand that you will not
+ extend the httpd's core hooks. Their presence and order in the request processing is in fact
+ a consequence of how they are called in <code>server/request.c</code>
+ (check <a href="./modguide.html#hooking">this section</a>
+ for an overview). The core hooks are listed in the
+ <a href="https://ci.apache.org/projects/httpd/trunk/doxygen/group__hooks.html">doxygen documentation</a>.</p>
+
+ <p>Reading <a href="./modguide.html">guide for developing modules</a> and
+ <a href="./request.html">request processing</a> before proceeding is
+ highly recomended.
+ </p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
<h2><a name="create" id="create">Creating a hook function</a></h2>
<p>In order to create a new hook, four things need to be
done:</p>
@@ -172,7 +190,8 @@ mode MODULE_VAR_EXPORT my_module =
<h3><a name="hooking-order" id="hooking-order">Controlling hook calling order</a></h3>
<p>In the example above, we didn't use the three arguments in
- the hook registration function that control calling order.
+ the hook registration function that control calling order of
+ all the functions registered within the hook.
There are two mechanisms for doing this. The first, rather
crude, method, allows us to specify roughly where the hook is
run relative to other modules. The final argument control this.
Modified: httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.xml?rev=1721974&r1=1721973&r2=1721974&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/developer/hooks.xml Mon Dec 28 18:24:39 2015
@@ -37,6 +37,23 @@
they get called in comparison to other modules.</p>
</summary>
+<section id="corehooks"><title>Core Hooks</title>
+ <p>The httpd's core modules offer a predefinined list of hooks
+ used during the standard <a href="./request.html">request processing</a>
+ phase. Creating a new hook will expose a function that
+ implements it (see sections below) but it is essential to undestand that you will not
+ extend the httpd's core hooks. Their presence and order in the request processing is in fact
+ a consequence of how they are called in <code>server/request.c</code>
+ (check <a href="./modguide.html#hooking">this section</a>
+ for an overview). The core hooks are listed in the
+ <a href="https://ci.apache.org/projects/httpd/trunk/doxygen/group__hooks.html">doxygen documentation</a>.</p>
+
+ <p>Reading <a href="./modguide.html">guide for developing modules</a> and
+ <a href="./request.html">request processing</a> before proceeding is
+ highly recomended.
+ </p>
+</section>
+
<section id="create"><title>Creating a hook function</title>
<p>In order to create a new hook, four things need to be
done:</p>
@@ -177,7 +194,8 @@ mode MODULE_VAR_EXPORT my_module =
<section id="hooking-order"><title>Controlling hook calling order</title>
<p>In the example above, we didn't use the three arguments in
- the hook registration function that control calling order.
+ the hook registration function that control calling order of
+ all the functions registered within the hook.
There are two mechanisms for doing this. The first, rather
crude, method, allows us to specify roughly where the hook is
run relative to other modules. The final argument control this.
Modified: httpd/httpd/branches/2.4.x/docs/manual/developer/index.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/developer/index.html.en?rev=1721974&r1=1721973&r2=1721974&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/developer/index.html.en (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/developer/index.html.en Mon Dec 28 18:24:39 2015
@@ -30,9 +30,8 @@
<div class="warning"><h3>Warning</h3>
<p>Many of the documents listed here are in need of update.
They are in different stages of progress.
- Please be patient, and point out any discrepancies or
- errors on the developer/ pages directly to the
- <a href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a> mailing list.</p>
+ Please be patient and follow <a href="https://httpd.apache.org/docs-project/">this link</a>
+ to propose a fix or point out any error/discrepancy.</p>
</div>
</div>
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#developing">2.4 development documents</a></li>
@@ -62,7 +61,9 @@
<div class="section">
<h2><a name="external" id="external">External Resources</a></h2>
<ul>
- <li><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/">Autogenerated Apache HTTP Server (trunk) code documentation</a></li>
+ <li><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/">Autogenerated Apache HTTP Server (trunk) code documentation</a> (the link is built by
+ this <a href="https://ci.apache.org/builders/httpd-doxygen-nightly">job</a>).
+ </li>
<li>Developer articles at <a href="http://www.apachetutor.org/">apachetutor</a> include:
<ul>
Modified: httpd/httpd/branches/2.4.x/docs/manual/developer/index.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/developer/index.xml?rev=1721974&r1=1721973&r2=1721974&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/developer/index.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/developer/index.xml Mon Dec 28 18:24:39 2015
@@ -29,10 +29,8 @@
<note type="warning"><title>Warning</title>
<p>Many of the documents listed here are in need of update.
They are in different stages of progress.
- Please be patient, and point out any discrepancies or
- errors on the developer/ pages directly to the
- <a href="http://httpd.apache.org/lists.html#http-dev"
- >dev@httpd.apache.org</a> mailing list.</p>
+ Please be patient and follow <a href="https://httpd.apache.org/docs-project/">this link</a>
+ to propose a fix or point out any error/discrepancy.</p>
</note>
</summary>
@@ -59,7 +57,9 @@
<ul>
<li><a
href="http://ci.apache.org/projects/httpd/trunk/doxygen/"
- >Autogenerated Apache HTTP Server (trunk) code documentation</a></li>
+ >Autogenerated Apache HTTP Server (trunk) code documentation</a> (the link is built by
+ this <a href="https://ci.apache.org/builders/httpd-doxygen-nightly">job</a>).
+ </li>
<li>Developer articles at <a href="http://www.apachetutor.org/">apachetutor</a> include:
<ul>
Modified: httpd/httpd/branches/2.4.x/docs/manual/developer/request.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/developer/request.html.en?rev=1721974&r1=1721973&r2=1721974&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/developer/request.html.en (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/developer/request.html.en Mon Dec 28 18:24:39 2015
@@ -63,15 +63,15 @@
<div class="section">
<h2><a name="processing" id="processing">The Request Processing Cycle</a></h2>
<p>All requests pass through <code>ap_process_request_internal()</code>
- in <code>request.c</code>, including subrequests and redirects. If a module
+ in <code>server/request.c</code>, including subrequests and redirects. If a module
doesn't pass generated requests through this code, the author is cautioned
that the module may be broken by future changes to request
processing.</p>
<p>To streamline requests, the module author can take advantage
- of the hooks offered to drop out of the request cycle early, or
- to bypass core hooks which are irrelevant (and costly in
- terms of CPU.)</p>
+ of the <a href="./modguide.html#hooking">hooks offered</a> to drop
+ out of the request cycle early, or to bypass core hooks which are
+ irrelevant (and costly in terms of CPU.)</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="parsing" id="parsing">The Request Parsing Phase</a></h2>
Modified: httpd/httpd/branches/2.4.x/docs/manual/developer/request.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/developer/request.xml?rev=1721974&r1=1721973&r2=1721974&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/developer/request.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/developer/request.xml Mon Dec 28 18:24:39 2015
@@ -56,15 +56,15 @@
<section id="processing"><title>The Request Processing Cycle</title>
<p>All requests pass through <code>ap_process_request_internal()</code>
- in <code>request.c</code>, including subrequests and redirects. If a module
+ in <code>server/request.c</code>, including subrequests and redirects. If a module
doesn't pass generated requests through this code, the author is cautioned
that the module may be broken by future changes to request
processing.</p>
<p>To streamline requests, the module author can take advantage
- of the hooks offered to drop out of the request cycle early, or
- to bypass core hooks which are irrelevant (and costly in
- terms of CPU.)</p>
+ of the <a href="./modguide.html#hooking">hooks offered</a> to drop
+ out of the request cycle early, or to bypass core hooks which are
+ irrelevant (and costly in terms of CPU.)</p>
</section>
<section id="parsing"><title>The Request Parsing Phase</title>