You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by nd...@apache.org on 2007/04/25 00:22:56 UTC
svn commit: r532108 - in /httpd/httpd/trunk/docs/manual:
developer/output-filters.html.en mod/mod_proxy.html.en mod/mod_proxy.xml.ja
Author: nd
Date: Tue Apr 24 15:22:49 2007
New Revision: 532108
URL: http://svn.apache.org/viewvc?view=rev&rev=532108
Log:
`build all`
Modified:
httpd/httpd/trunk/docs/manual/developer/output-filters.html.en
httpd/httpd/trunk/docs/manual/mod/mod_proxy.html.en
httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml.ja
Modified: httpd/httpd/trunk/docs/manual/developer/output-filters.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/developer/output-filters.html.en?view=diff&rev=532108&r1=532107&r2=532108
==============================================================================
--- httpd/httpd/trunk/docs/manual/developer/output-filters.html.en (original)
+++ httpd/httpd/trunk/docs/manual/developer/output-filters.html.en Tue Apr 24 15:22:49 2007
@@ -87,7 +87,8 @@
covers a case where filters are encouraged to generate
<code>FLUSH</code> buckets.</p>
- <div class="example"><h3>Example bucket brigade</h3><pre>HEAP FLUSH FILE EOS</pre></div>
+ <div class="example"><h3>Example bucket brigade</h3><p><code>
+ HEAP FLUSH FILE EOS</code></p></div>
<p>This shows a bucket brigade which may be passed to a filter; it
contains two metadata buckets (<code>FLUSH</code> and
@@ -122,12 +123,18 @@
filter chain. But, for good defensive programming, filters should
be prepared to accept an empty brigade, and do nothing.</p>
- <div class="example"><h3>How to handle an empty brigade</h3><pre>apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
-{
- if (APR_BRIGADE_EMPTY(bb)) {
- return APR_SUCCESS;
- }
- ....</pre></div>
+ <div class="example"><h3>How to handle an empty brigade</h3><p><code>
+ apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)<br />
+ {<br />
+ <span class="indent">
+ if (APR_BRIGADE_EMPTY(bb)) {<br />
+ <span class="indent">
+ return APR_SUCCESS;<br />
+ </span>
+ }<br />
+ ....<br />
+ </span>
+ </code></p></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
@@ -145,7 +152,7 @@
<p>There are a variety of functions and macros for traversing and
manipulating bucket brigades; see the <a href="http://apr.apache.org/docs/apr-util/trunk/group___a_p_r___util___bucket___brigades.html">apr_bucket.h</a>
- header for complete coverage. Commonly used macros include:
+ header for complete coverage. Commonly used macros include:</p>
<dl>
<dt><code>APR_BRIGADE_FIRST(bb)</code></dt>
@@ -160,7 +167,7 @@
<dt><code>APR_BUCKET_PREV(e)</code></dt>
<dd>gives the bucket before bucket e</dd>
- </dl></p>
+ </dl>
<p>The <code>apr_bucket_brigade</code> structure itself is
allocated out of a pool, so if a filter creates a new brigade, it
@@ -194,7 +201,7 @@
<p>When dealing with non-metadata buckets, it is important to
understand that the "<code>apr_bucket *</code>" object is an
- abstract <em>representation</em> of data:
+ abstract <em>representation</em> of data:</p>
<ol>
<li>The amount of data represented by the bucket may or may not
@@ -209,7 +216,7 @@
represents data stored in a file on disk.</li>
</ol>
- Filters read the data from a bucket using the
+ <p>Filters read the data from a bucket using the
<code>apr_bucket_read</code> function. When this function is
invoked, the bucket may <em>morph</em> into a different bucket
type, and may also insert a new bucket into the bucket brigade.
@@ -220,7 +227,7 @@
single <code>FILE</code> bucket representing an entire file, 24
kilobytes in size:</p>
- <div class="example"><pre>FILE(0K-24K)</pre></div>
+ <div class="example"><p><code>FILE(0K-24K)</code></p></div>
<p>When this bucket is read, it will read a block of data from the
file, morph into a <code>HEAP</code> bucket to represent that
@@ -229,7 +236,7 @@
after the <code>apr_bucket_read</code> call, the brigade looks
like:</p>
- <div class="example"><pre>HEAP(8K) FILE(8K-24K)</pre></div>
+ <div class="example"><p><code>HEAP(8K) FILE(8K-24K)</code></p></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
@@ -242,20 +249,24 @@
loop is critical to producing a well-behaved output filter.</p>
<p>Taking an example which loops through the entire brigade as
- follows:
+ follows:</p>
- <div class="example"><h3>Bad output filter -- do not imitate!</h3><pre>apr_bucket *e = APR_BRIGADE_FIRST(bb);
-const char *data;
-apr_size_t len;
-
-while (e != APR_BRIGADE_SENTINEL(bb)) {
- apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
- e = APR_BUCKET_NEXT(e);
-}
-
-return ap_pass_brigade(bb);</pre></div>
+ <div class="example"><h3>Bad output filter -- do not imitate!</h3><p><code>
+ apr_bucket *e = APR_BRIGADE_FIRST(bb);<br />
+const char *data;<br />
+apr_size_t len;<br />
+<br />
+while (e != APR_BRIGADE_SENTINEL(bb)) {<br />
+<span class="indent">
+ apr_bucket_read(e, &data, &length, APR_BLOCK_READ);<br />
+ e = APR_BUCKET_NEXT(e);<br />
+</span>
+}<br />
+<br />
+return ap_pass_brigade(bb);
+ </code></p></div>
- The above implementation would consume memory proportional to
+ <p>The above implementation would consume memory proportional to
content size. If passed a <code>FILE</code> bucket, for example,
the entire file contents would be read into memory as each
<code>apr_bucket_read</code> call morphed a <code>FILE</code>
@@ -265,22 +276,26 @@
amount of memory to filter any brigade; a temporary brigade is
needed and must be allocated only once per response, see the <a href="#state">Maintaining state</a> section.</p>
- <div class="example"><h3>Better output filter</h3><pre>apr_bucket *e;
-const char *data;
-apr_size_t len;
-
-while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
- rv = apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
- if (rv) ...;
- /* Remove bucket e from bb. */
- APR_BUCKET_REMOVE(e);
- /* Insert it into temporary brigade. */
- APR_BRIGADE_INSERT_HEAD(tmpbb, e);
- /* Pass brigade downstream. */
- rv = ap_pass_brigade(f->next, tmpbb);
- if (rv) ...;
- apr_brigade_cleanup(tmpbb);
-}</pre></div>
+ <div class="example"><h3>Better output filter</h3><p><code>
+apr_bucket *e;<br />
+const char *data;<br />
+apr_size_t len;<br />
+<br />
+while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {<br />
+<span class="indent">
+ rv = apr_bucket_read(e, &data, &length, APR_BLOCK_READ);<br />
+ if (rv) ...;<br />
+ /* Remove bucket e from bb. */<br />
+ APR_BUCKET_REMOVE(e);<br />
+ /* Insert it into temporary brigade. */<br />
+ APR_BRIGADE_INSERT_HEAD(tmpbb, e);<br />
+ /* Pass brigade downstream. */<br />
+ rv = ap_pass_brigade(f->next, tmpbb);<br />
+ if (rv) ...;<br />
+ apr_brigade_cleanup(tmpbb);<br />
+</span>
+}
+ </code></p></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
@@ -294,26 +309,35 @@
temporary brigade in such a structure, to avoid having to allocate
a new brigade per invocation as described in the <a href="#brigade">Brigade structure</a> section.</p>
- <div class="example"><h3>Example code to maintain filter state</h3><pre>struct dummy_state {
- apr_bucket_brigade *tmpbb;
- int filter_state;
- ....
-};
-
-apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
-{
- struct dummy_state *state;
-
- state = f->ctx;
- if (state == NULL) {
- /* First invocation for this response: initialise state structure. */
- f->ctx = state = apr_palloc(sizeof *state, f->r->pool);
-
- state->tmpbb = apr_brigade_create(f->r->pool, f->c->bucket_alloc);
- state->filter_state = ...;
- }
- ...</pre></div>
-
+ <div class="example"><h3>Example code to maintain filter state</h3><p><code>
+struct dummy_state {<br />
+<span class="indent">
+ apr_bucket_brigade *tmpbb;<br />
+ int filter_state;<br />
+ ....<br />
+</span>
+};<br />
+<br />
+apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)<br />
+{<br />
+<span class="indent">
+ struct dummy_state *state;<br />
+<br />
+ state = f->ctx;<br />
+ if (state == NULL) {<br />
+ <span class="indent">
+ /* First invocation for this response: initialise state structure.
+ */<br />
+ f->ctx = state = apr_palloc(sizeof *state, f->r->pool);<br />
+<br />
+ state->tmpbb = apr_brigade_create(f->r->pool, f->c->bucket_alloc);<br />
+ state->filter_state = ...;<br />
+ </span>
+ }<br />
+ ...
+</span>
+ </code></p></div>
+
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="buffer" id="buffer">Buffering buckets</a></h2>
@@ -337,7 +361,7 @@
used, which will move all the buckets into a separate brigade
containing buckets with a lifetime as long as the given pool
argument. This function must be used with care, taking into
- account the following points:
+ account the following points:</p>
<ol>
<li>On return, <code>ap_save_brigade</code> guarantees that all
@@ -356,7 +380,7 @@
non-NULL "<code>saveto</code>" (destination) brigade parameter,
the function will create a new brigade, which may cause memory
use to be proportional to content size as described in the <a href="#brigade">Brigade structure</a> section.</li>
- </ol></p>
+ </ol>
<div class="warning">Filters must ensure that any buffered data is
processed and passed down the filter chain during the last
@@ -386,31 +410,40 @@
script; reading from such a bucket will block when waiting for the
CGI script to produce more output.</p>
- <div class="example"><h3>Example code using non-blocking bucket reads</h3><pre>apr_bucket *e;
-apr_read_type_e mode = APR_NONBLOCK_READ;
-
-while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
- apr_status_t rv;
-
- rv = apr_bucket_read(e, &data, &length, mode);
- if (rv == APR_EAGAIN && mode == APR_NONBLOCK_READ) {
- /* Pass down a brigade containing a flush bucket: */
- APR_BRIGADE_INSERT_TAIL(tmpbb, apr_bucket_flush_create(...));
- rv = ap_pass_brigade(f->next, tmpbb);
- apr_brigade_cleanup(tmpbb);
- if (rv != APR_SUCCESS) return rv;
-
- /* Retry, using a blocking read. */
- mode = APR_BLOCK_READ;
- continue;
- } else if (rv != APR_SUCCESS) {
- /* handle errors */
- }
-
- /* Next time, try a non-blocking read first. */
- mode = APR_NONBLOCK_READ;
- ...
-}</pre></div>
+ <div class="example"><h3>Example code using non-blocking bucket reads</h3><p><code>
+
+apr_bucket *e;<br />
+apr_read_type_e mode = APR_NONBLOCK_READ;<br />
+<br />
+while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {<br />
+<span class="indent">
+ apr_status_t rv;<br />
+<br />
+ rv = apr_bucket_read(e, &data, &length, mode);<br />
+ if (rv == APR_EAGAIN && mode == APR_NONBLOCK_READ) {<br />
+ <span class="indent">
+ /* Pass down a brigade containing a flush bucket: */<br />
+ APR_BRIGADE_INSERT_TAIL(tmpbb, apr_bucket_flush_create(...));<br />
+ rv = ap_pass_brigade(f->next, tmpbb);<br />
+ apr_brigade_cleanup(tmpbb);<br />
+ if (rv != APR_SUCCESS) return rv;<br />
+<br />
+ /* Retry, using a blocking read. */<br />
+ mode = APR_BLOCK_READ;<br />
+ continue;<br />
+ </span>
+ } else if (rv != APR_SUCCESS) {<br />
+ <span class="indent">
+ /* handle errors */<br />
+ </span>
+ }<br />
+<br />
+ /* Next time, try a non-blocking read first. */<br />
+ mode = APR_NONBLOCK_READ;<br />
+ ...<br />
+</span>
+}
+ </code></p></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
Modified: httpd/httpd/trunk/docs/manual/mod/mod_proxy.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_proxy.html.en?view=diff&rev=532108&r1=532107&r2=532108
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_proxy.html.en (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_proxy.html.en Tue Apr 24 15:22:49 2007
@@ -324,8 +324,8 @@
and later.</td></tr>
</table>
<p>This directive adds a member to a load balancing group. It must be used
- within a <code class="directive"><a href="#<proxy balancer://...>"><Proxy balancer://...></a></code> container directive, and can take any
- of the parameters available to
+ within a <code><Proxy <var>balancer://</var>...></code> container
+ directive, and can take any of the parameters available to
<code class="directive"><a href="#proxypass">ProxyPass</a></code> directives.</p>
<p>One additional parameter is available only to <code class="directive"><a href="#balancermember">BalancerMember</a></code> directives:
<var>loadfactor</var>. This is the member load factor - a number between 1
Modified: httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml.ja
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml.ja?view=diff&rev=532108&r1=532107&r2=532108
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml.ja [iso-2022-jp] (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml.ja [iso-2022-jp] Tue Apr 24 15:22:49 2007
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="iso-2022-jp"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 189754:527969 (outdated) -->
+<!-- English Revision: 189754:532107 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more