From: Bill Stoddard Date: Sun, 30 Jul 2000 04:12:37 +0000 (+0000) Subject: mod_file_cache docco X-Git-Tag: APACHE_2_0_ALPHA_5~39 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=b3e80b6a0fe8098176a3cc792df2da2fe7008cb0;p=apache mod_file_cache docco git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@85947 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/index.html b/docs/manual/mod/index.html index 3b88ccc4f7..908276364a 100644 --- a/docs/manual/mod/index.html +++ b/docs/manual/mod/index.html @@ -74,6 +74,8 @@ mod_usertrack

Demonstrates Apache API

mod_expires Apache 1.2 and up

Apply Expires: headers to resources +

mod_file_cache +

Caching files in memory for faster serving.

mod_headers Apache 1.2 and up

Add arbitrary HTTP headers to resources

mod_imap @@ -97,8 +99,6 @@ mod_log_config module in Apache 1.2 and up

Determining document types using file extensions.

mod_mime_magic

Determining document types using "magic numbers". -

mod_mmap_static -

Mapping files into memory for faster serving.

mod_negotiation

Content negotiation.

mod_proxy diff --git a/docs/manual/mod/mod_file_cache.html b/docs/manual/mod/mod_file_cache.html new file mode 100644 index 0000000000..6abbdcb9e3 --- /dev/null +++ b/docs/manual/mod/mod_file_cache.html @@ -0,0 +1,267 @@ + + + + Apache module mod_file_cache + + + + +

Module mod_file_cache

+ This module should be used with care. You can easily create a + broken site using mod_file_cache, so read this document + carefully. +

+ +

+ Caching frequently requested files that change very + infrequently is a technique for reducing server load. mod_file_cache + provides two techniques for caching frequently requested + static 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 file handle. 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. +

+ +

+ mod_file_cache is not compiled into the server by + default. To use mod_file_cache you have to enable the + following line in the server build Configuration file: +

+    AddModule  modules/experimental/mod_file_cache.o
+

+ +

+ 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. +

+ +

+ This module is an extension of and borrows heavily from the + mod_mmap_static module in Apache 1.3. +

Summary

+ mod_file_cache caches a list of statically configured + files via MMapFile or CacheFile directives + in the main server configuration. +

+ +

+ Not all platforms support both directives. For + example, Apache on Windows does not currently support the MMapStatic + 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. +

+ +

`MmapFile` Directive

+ The MmapFile directive of mod_file_cache + maps a list of statically configured files into memory through the + system call mmap(). 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. +

+ This mmap()ing is done once at server start or restart, only. So whenever + one of the mapped files changes on the filesystem you have to + restart the server (see the Stopping and + Restarting documentation). To reiterate that point: if the + files are modified in place 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 rdist and + mv do this. The reason why this modules doesn't take + care of changes to the files is that this check would need an extra + stat() every time which is a waste and against the + intent of I/O reduction. +

+ +

`CacheFile` Directive

+ The CacheFile directive of mod_file_cache + opens an active handle or file descriptor 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. +

+ Insert more details about sendfile API... +

+ 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 have to restart the server (see the Stopping and Restarting documentation). + To reiterate that point: if the files are modified in + place 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 rdist and mv do this. +

+ +

Directives

MMapFile +
CacheFile +

+ +

MMapFile

+ Syntax: MMapFile filename ... +
+ Default: None +
+ Context: server-config +
+ Override: Not applicable +
+ Status: Experimental +
+ Module: mod_file_cache +
+ Compatibility: Only in Apache 1.3 (via + mod_mmap_statis) or later. + +

+ The MMapFile 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. +

+ +

+ Be careful with the filename 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 etc. because that again would cost extra stat() + system calls which is not acceptable. This module may or may not work + with filenames rewritten by mod_alias or + mod_rewrite. +

+ + Example: + +

+  MMapFile /usr/local/apache/htdocs/index.html
+

+ + +

CacheFile

+ Syntax: CacheFile filename ... +
+ Default: None +
+ Context: server-config +
+ Override: Not applicable +
+ Status: Experimental +
+ Module: mod_file_cache +
+ Compatibility: Only available in Apache 2.0 or later. + +

+ The CacheFile 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. +

+ +

+ + Example: + +

+  CacheFile /usr/local/apache/htdocs/index.html
+

+ +

+ Note: don't bother asking for a for a directive which + recursively caches all the files in a directory. Try this + instead... + See the Include directive, and consider this command: +

+  find /www/htdocs -type f -print \
+  | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
+

+ + + +