2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Copyright 2002-2005 The Apache Software Foundation or its licensors,
10 Licensed under the Apache License, Version 2.0 (the "License");
11 you may not use this file except in compliance with the License.
12 You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_file_cache.xml.meta">
25 <name>mod_file_cache</name>
26 <description>Caches a static list of files in memory</description>
27 <status>Experimental</status>
28 <sourcefile>mod_file_cache.c</sourcefile>
29 <identifier>file_cache_module</identifier>
34 This module should be used with care. You can easily create a broken
35 site using <module>mod_file_cache</module>, so read this document
39 <p><em>Caching</em> frequently requested files that change very
40 infrequently is a technique for reducing server load.
41 <module>mod_file_cache</module> provides two techniques for caching
42 frequently requested <em>static</em> files. Through configuration
43 directives, you can direct <module>mod_file_cache</module> to either
44 open then <code>mmap()</code> a file, or to pre-open a file and save
45 the file's open <em>file handle</em>. Both techniques reduce server
46 load when processing requests for these files by doing part of the work
47 (specifically, the file I/O) for serving the file when the
48 server is started rather than during each request.</p>
50 <p>Notice: You cannot use this for speeding up CGI programs or
51 other files which are served by special content handlers. It
52 can only be used for regular files which are usually served by
53 the Apache core content handler.</p>
55 <p>This module is an extension of and borrows heavily from the
56 <code>mod_mmap_static</code> module in Apache 1.3.</p>
59 <section id="using"><title>Using mod_file_cache</title>
61 <p><module>mod_file_cache</module> caches a list of statically
62 configured files via <directive module="mod_file_cache"
63 >MMapFile</directive> or <directive module="mod_file_cache"
64 >CacheFile</directive> directives in the main server configuration.</p>
66 <p>Not all platforms support both directives. For example, Apache
67 on Windows does not currently support the <directive
68 module="mod_file_cache">MMapStatic</directive> directive, while
69 other platforms, like AIX, support both. You will receive an error
70 message in the server error log if you attempt to use an
71 unsupported directive. If given an unsupported directive, the
72 server will start but the file will not be cached. On platforms
73 that support both directives, you should experiment with both to
74 see which works best for you.</p>
76 <section><title>MMapFile Directive</title>
78 <p>The <directive module="mod_file_cache">MMapFile</directive>
79 directive of <module>mod_file_cache</module> maps a list of
80 statically configured files into memory through the system call
81 <code>mmap()</code>. This system call is available on most modern
82 Unix derivates, but not on all. There are sometimes system-specific
83 limits on the size and number of files that can be
84 <code>mmap()</code>ed, experimentation is probably the easiest way
87 <p>This <code>mmap()</code>ing is done once at server start or
88 restart, only. So whenever one of the mapped files changes on the
89 filesystem you <em>have</em> to restart the server (see the <a
90 href="../stopping.html">Stopping and Restarting</a> documentation).
91 To reiterate that point: if the files are modified <em>in place</em>
92 without restarting the server you may end up serving requests that
93 are completely bogus. You should update files by unlinking the old
94 copy and putting a new copy in place. Most tools such as
95 <code>rdist</code> and <code>mv</code> do this. The reason why this
96 modules doesn't take care of changes to the files is that this check
97 would need an extra <code>stat()</code> every time which is a waste
98 and against the intent of I/O reduction.</p>
101 <section><title>CacheFile Directive</title>
103 <p>The <directive module="mod_file_cache">CacheFile</directive>
104 directive of <module>mod_file_cache</module> opens an active
105 <em>handle</em> or <em>file descriptor</em> to the file (or files)
106 listed in the configuration directive and places these open file
107 handles in the cache. When the file is requested, the server
108 retrieves the handle from the cache and passes it to the
109 <code>sendfile()</code> (or <code>TransmitFile()</code> on Windows),
113 <p>Insert more details about sendfile API...</p>
116 <p>This file handle caching is done once at server start or
117 restart, only. So whenever one of the cached files changes on
118 the filesystem you <em>have</em> to restart the server (see the
119 <a href="../stopping.html">Stopping and Restarting</a>
120 documentation). To reiterate that point: if the files are
121 modified <em>in place</em> without restarting the server you
122 may end up serving requests that are completely bogus. You
123 should update files by unlinking the old copy and putting a new
124 copy in place. Most tools such as <code>rdist</code> and
125 <code>mv</code> do this.</p>
128 <note><title>Note</title>
129 <p>Don't bother asking for a directive which recursively
130 caches all the files in a directory. Try this instead... See the
131 <directive module="core">Include</directive> directive, and consider
135 find /www/htdocs -type f -print \<br />
136 | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
142 <name>MMapFile</name>
143 <description>Map a list of files into memory at startup time</description>
144 <syntax>MMapFile <var>file-path</var> [<var>file-path</var>] ...</syntax>
145 <contextlist><context>server config</context></contextlist>
148 <p>The <directive>MMapFile</directive> directive maps one or more files
149 (given as whitespace separated arguments) into memory at server
150 startup time. They are automatically unmapped on a server
151 shutdown. When the files have changed on the filesystem at
152 least a <code>HUP</code> or <code>USR1</code> signal should be send to
153 the server to re-<code>mmap()</code> them.</p>
155 <p>Be careful with the <var>file-path</var> arguments: They have
156 to literally match the filesystem path Apache's URL-to-filename
157 translation handlers create. We cannot compare inodes or other
158 stuff to match paths through symbolic links <em>etc.</em>
159 because that again would cost extra <code>stat()</code> system
160 calls which is not acceptable. This module may or may not work
161 with filenames rewritten by <module>mod_alias</module> or
162 <module>mod_rewrite</module>.</p>
164 <example><title>Example</title>
165 MMapFile /usr/local/apache/htdocs/index.html
171 <name>CacheFile</name>
172 <description>Cache a list of file handles at startup time</description>
173 <syntax>CacheFile <var>file-path</var> [<var>file-path</var>] ...</syntax>
174 <contextlist><context>server config</context></contextlist>
177 <p>The <directive>CacheFile</directive> directive opens handles to
178 one or more files (given as whitespace separated arguments) and
179 places these handles into the cache at server startup
180 time. Handles to cached files are automatically closed on a server
181 shutdown. When the files have changed on the filesystem, the
182 server should be restarted to to re-cache them.</p>
184 <p>Be careful with the <var>file-path</var> arguments: They have
185 to literally match the filesystem path Apache's URL-to-filename
186 translation handlers create. We cannot compare inodes or other
187 stuff to match paths through symbolic links <em>etc.</em>
188 because that again would cost extra <code>stat()</code> system
189 calls which is not acceptable. This module may or may not work
190 with filenames rewritten by <module>mod_alias</module> or
191 <module>mod_rewrite</module>.</p>
193 <example><title>Example</title>
194 CacheFile /usr/local/apache/htdocs/index.html