| <?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. 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 derivatives, 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> |
| <highlight language="config"> |
| MMapFile /usr/local/apache/htdocs/index.html |
| </highlight> |
| </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 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> |
| <highlight language="config"> |
| CacheFile /usr/local/apache/htdocs/index.html |
| </highlight> |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| </modulesynopsis> |