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 2002/11/14 05:06:10 UTC
cvs commit: httpd-2.0/docs/manual/mod mod_file_cache.xml
nd 2002/11/13 20:06:08
Modified: docs/manual/mod mod_file_cache.xml
Log:
- add directive <description>s
- <em> -> <var>
- some reformatting and markup improvement
Revision Changes Path
1.3 +93 -91 httpd-2.0/docs/manual/mod/mod_file_cache.xml
Index: mod_file_cache.xml
===================================================================
RCS file: /home/cvs/httpd-2.0/docs/manual/mod/mod_file_cache.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- mod_file_cache.xml 23 May 2002 14:50:11 -0000 1.2
+++ mod_file_cache.xml 14 Nov 2002 04:06:08 -0000 1.3
@@ -11,20 +11,20 @@
<summary>
-<note type="warning">
-This module should be used with care. You can easily
- create a broken site using mod_file_cache, so read this
- document carefully.
-</note>
+ <note type="warning">
+ This module should be used with care. You can easily create a broken
+ site using <module>mod_file_cache</module>, so read this document
+ carefully.
+ </note>
<p><em>Caching</em> frequently requested files that change very
infrequently is a technique for reducing server load.
- mod_file_cache provides two techniques for caching frequently
- requested <em>static</em> files. Through configuration
- directives, you can direct mod_file_cache to either open then
- mmap()a file, or to pre-open a file and save the file's open
- <em>file handle</em>. Both techniques reduce server load when
- processing requests for these files by doing part of the work
+ <module>mod_file_cache</module> provides two techniques for caching
+ frequently requested <em>static</em> files. Through configuration
+ directives, you can direct <module>mod_file_cache</module> to either
+ open then <code>mmap()</code> a file, or to pre-open a file and save
+ the file's open <em>file handle</em>. Both techniques reduce server
+ load when processing requests for these files by doing part of the work
(specifically, the file I/O) for serving the file when the
server is started rather than during each request.</p>
@@ -34,16 +34,15 @@
the Apache core content handler.</p>
<p>This module is an extension of and borrows heavily from the
- mod_mmap_static module in Apache 1.3.</p>
+ <code>mod_mmap_static</code> module in Apache 1.3.</p>
</summary>
-<section><title>Using mod_file_cache</title>
+<section id="using"><title>Using mod_file_cache</title>
<p><module>mod_file_cache</module> caches a list of statically
- configured files via <directive
- module="mod_file_cache">MMapFile</directive> or <directive
- module="mod_file_cache">CacheFile</directive> directives in the
- main server configuration.</p>
+ configured files via <directive module="mod_file_cache"
+ >MMapFile</directive> or <directive module="mod_file_cache"
+ >CacheFile</directive> directives in the main server configuration.</p>
<p>Not all platforms support both directives. For example, Apache
on Windows does not currently support the <directive
@@ -55,72 +54,75 @@
that support both directives, you should experiment with both to
see which works best for you.</p>
-<section><title>MmapFile Directive</title>
-
- <p>The <directive module="mod_file_cache">MmapFile</directive>
- directive of <module>mod_file_cache</module> maps a list of
- statically configured files into memory through the system call
- <code>mmap()</code>. This system call is available on most modern
- Unix derivates, but not on all. There are sometimes
- system-specific limits on the size and number of files that can be
- mmap()d, experimentation is probably the easiest way to find
- out.</p>
-
- <p>This mmap()ing is done once at server start or restart,
- only. So whenever one of the mapped files changes on the
- filesystem you <em>have</em> to restart the server (see the <a
- href="../stopping.html">Stopping and Restarting</a>
- documentation). To reiterate that point: if the files are
- modified <em>in place</em> without restarting the server you
- may end up serving requests that are completely bogus. You
- should update files by unlinking the old copy and putting a new
- copy in place. Most tools such as <code>rdist</code> and
- <code>mv</code> do this. The reason why this modules doesn't
- take care of changes to the files is that this check would need
- an extra <code>stat()</code> every time which is a waste and
- against the intent of I/O reduction.</p>
-</section>
-
-<section><title>CacheFile Directive</title>
-
- <p>The <directive module="mod_file_cache">CacheFile</directive>
- directive of <module>mod_file_cache</module> opens an active
- <em>handle</em> or <em>file descriptor</em> to the file (or files)
- listed in the configuration directive and places these open file
- handles in the cache. When the file is requested, the server
- retrieves the handle from the cache and passes it to the
- sendfile() (or TransmitFile() on Windows), socket API.</p>
-
- <p>Insert more details about sendfile API...</p>
-
- <p>This file handle caching is done once at server start or
- restart, only. So whenever one of the cached files changes on
- the filesystem you <em>have</em> to restart the server (see the
- <a href="../stopping.html">Stopping and Restarting</a>
- documentation). To reiterate that point: if the files are
- modified <em>in place</em> without restarting the server you
- may end up serving requests that are completely bogus. You
- should update files by unlinking the old copy and putting a new
- copy in place. Most tools such as <code>rdist</code> and
- <code>mv</code> do this.</p>
-</section>
-
-<note><title>Note</title> Don't bother asking for a for a
- directive which recursively caches all the files in a
- directory. Try this instead... See the
- <directive module="core">Include</directive> directive, and consider
- this command:
-<example>
- find /www/htdocs -type f -print \ <br />
- | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
-</example>
-</note>
+ <section><title>MMapFile Directive</title>
+ <p>The <directive module="mod_file_cache">MMapFile</directive>
+ directive of <module>mod_file_cache</module> maps a list of
+ statically configured files into memory through the system call
+ <code>mmap()</code>. This system call is available on most modern
+ Unix derivates, but not on all. There are sometimes system-specific
+ limits on the size and number of files that can be
+ <code>mmap()</code>ed, experimentation is probably the easiest way
+ to find out.</p>
+
+ <p>This <code>mmap()</code>ing is done once at server start or
+ restart, only. So whenever one of the mapped files changes on the
+ filesystem you <em>have</em> to restart the server (see the <a
+ href="../stopping.html">Stopping and Restarting</a> documentation).
+ To reiterate that point: if the files are modified <em>in place</em>
+ without restarting the server you may end up serving requests that
+ are completely bogus. You should update files by unlinking the old
+ copy and putting a new copy in place. Most tools such as
+ <code>rdist</code> and <code>mv</code> do this. The reason why this
+ modules doesn't take care of changes to the files is that this check
+ would need an extra <code>stat()</code> every time which is a waste
+ and against the intent of I/O reduction.</p>
+ </section>
+
+ <section><title>CacheFile Directive</title>
+
+ <p>The <directive module="mod_file_cache">CacheFile</directive>
+ directive of <module>mod_file_cache</module> opens an active
+ <em>handle</em> or <em>file descriptor</em> to the file (or files)
+ listed in the configuration directive and places these open file
+ handles in the cache. When the file is requested, the server
+ retrieves the handle from the cache and passes it to the
+ <code>sendfile()</code> (or <code>TransmitFile()</code> on Windows),
+ socket API.</p>
+
+ <!-- XXX
+ <p>Insert more details about sendfile API...</p>
+ -->
+
+ <p>This file handle caching is done once at server start or
+ restart, only. So whenever one of the cached files changes on
+ the filesystem you <em>have</em> to restart the server (see the
+ <a href="../stopping.html">Stopping and Restarting</a>
+ documentation). To reiterate that point: if the files are
+ modified <em>in place</em> without restarting the server you
+ may end up serving requests that are completely bogus. You
+ should update files by unlinking the old copy and putting a new
+ copy in place. Most tools such as <code>rdist</code> and
+ <code>mv</code> do this.</p>
+ </section>
+
+ <note><title>Note</title>
+ <p>Don't bother asking for a for a directive which recursively
+ caches all the files in a directory. Try this instead... See the
+ <directive module="core">Include</directive> directive, and consider
+ this command:</p>
+
+ <example>
+ find /www/htdocs -type f -print \<br />
+ | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
+ </example>
+ </note>
</section>
<directivesynopsis>
<name>MMapFile</name>
-<syntax>MMapFile <em>file-path</em> [<em>file-path</em>] ...</syntax>
+<description>Map a list of files into memory at startup time</description>
+<syntax>MMapFile <var>file-path</var> [<var>file-path</var>] ...</syntax>
<contextlist><context>server config</context></contextlist>
<usage>
@@ -128,10 +130,10 @@
(given as whitespace separated arguments) into memory at server
startup time. They are automatically unmapped on a server
shutdown. When the files have changed on the filesystem at
- least a HUP or USR1 signal should be send to the server to
- re-mmap them.</p>
+ least a <code>HUP</code> or <code>USR1</code> signal should be send to
+ the server to re-<code>mmap()</code> them.</p>
- <p>Be careful with the <em>file-path</em> arguments: They have
+ <p>Be careful with the <var>file-path</var> arguments: They have
to literally match the filesystem path Apache's URL-to-filename
translation handlers create. We cannot compare inodes or other
stuff to match paths through symbolic links <em>etc.</em>
@@ -140,16 +142,16 @@
with filenames rewritten by <module>mod_alias</module> or
<module>mod_rewrite</module>.</p>
-<example><title>Example</title>
- MMapFile /usr/local/apache/htdocs/index.html
-</example>
+ <example><title>Example</title>
+ MMapFile /usr/local/apache/htdocs/index.html
+ </example>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>CacheFile</name>
-<syntax>CacheFile
- <em>file-path</em> [<em>file-path</em>] ...</syntax>
+<description>Cache a list of file handles at startup time</description>
+<syntax>CacheFile <var>file-path</var> [<var>file-path</var>] ...</syntax>
<contextlist><context>server config</context></contextlist>
<usage>
@@ -160,7 +162,7 @@
shutdown. When the files have changed on the filesystem, the
server should be restarted to to re-cache them.</p>
- <p>Be careful with the <em>file-path</em> arguments: They have
+ <p>Be careful with the <var>file-path</var> arguments: They have
to literally match the filesystem path Apache's URL-to-filename
translation handlers create. We cannot compare inodes or other
stuff to match paths through symbolic links <em>etc.</em>
@@ -169,10 +171,10 @@
with filenames rewritten by <module>mod_alias</module> or
<module>mod_rewrite</module>.</p>
-<example><title>Example</title>
- CacheFile /usr/local/apache/htdocs/index.html
-</example>
+ <example><title>Example</title>
+ CacheFile /usr/local/apache/htdocs/index.html
+ </example>
</usage>
-
</directivesynopsis>
+
</modulesynopsis>