mirror of
https://github.com/apache/httpd.git
synced 2025-05-30 01:07:09 +03:00
44fa6e0073
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@420990 13f79535-47bb-0310-9956-ffa450edef68
200 lines
8.9 KiB
XML
200 lines
8.9 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_file_cache.xml.meta">
|
|
|
|
<name>mod_file_cache</name>
|
|
<description>Caches a static list of files in memory</description>
|
|
<status>Experimental</status>
|
|
<sourcefile>mod_file_cache.c</sourcefile>
|
|
<identifier>file_cache_module</identifier>
|
|
|
|
<summary>
|
|
|
|
<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.
|
|
<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>
|
|
|
|
<p>Notice: You cannot use this for speeding up CGI programs or
|
|
other files which are served by special content handlers. It
|
|
can only be used for regular files which are usually served by
|
|
the Apache core content handler.</p>
|
|
|
|
<p>This module is an extension of and borrows heavily from the
|
|
<code>mod_mmap_static</code> module in Apache 1.3.</p>
|
|
</summary>
|
|
|
|
<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>
|
|
|
|
<p>Not all platforms support both directives. For example, Apache
|
|
on Windows does not currently support the <directive
|
|
module="mod_file_cache">MMapStatic</directive> directive, while
|
|
other platforms, like AIX, support both. You will receive an error
|
|
message in the server error log if you attempt to use an
|
|
unsupported directive. If given an unsupported directive, the
|
|
server will start but the file will not be cached. On platforms
|
|
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
|
|
<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 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>
|
|
<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>
|
|
<p>The <directive>MMapFile</directive> directive maps one or more files
|
|
(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 <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 <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>
|
|
because that again would cost extra <code>stat()</code> system
|
|
calls which is not acceptable. This module may or may not work
|
|
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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>CacheFile</name>
|
|
<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>
|
|
<p>The <directive>CacheFile</directive> directive opens handles to
|
|
one or more files (given as whitespace separated arguments) and
|
|
places these handles into the cache at server startup
|
|
time. Handles to cached files are automatically closed on a server
|
|
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 <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>
|
|
because that again would cost extra <code>stat()</code> system
|
|
calls which is not acceptable. This module may or may not work
|
|
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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
</modulesynopsis>
|