| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> |
| <modulesynopsis> |
| |
| <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 mod_file_cache, 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 |
| (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 |
| mod_mmap_static module in Apache 1.3.</p> |
| </summary> |
| |
| <section><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 |
| 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> |
| |
| <directivesynopsis> |
| <name>MMapFile</name> |
| <syntax>MMapFile <em>file-path</em> [<em>file-path</em>] ...</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 HUP or USR1 signal should be send to the server to |
| re-mmap them.</p> |
| |
| <p>Be careful with the <em>file-path</em> 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> |
| <syntax>CacheFile |
| <em>file-path</em> [<em>file-path</em>] ...</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 <em>file-path</em> 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> |