Apache Module mod_file_cache

Available Languages: en | - ko

- - - -

Description:	Caches a static list of files in memory
Status:	Experimental
Module Identifier:	file_cache_module
Source File:	mod_file_cache.c

Summary

- - -

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

- -

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.

Topics

Using mod_file_cache

Using mod_file_cache

- -

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()ed, 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.

- - - -

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.

- - -

Note

Don't bother asking 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 -

CacheFile Directive

- - - - - - -

Description:	Cache a list of file handles at startup time
Syntax:	`CacheFile file-path [file-path] ...`
Context:	server config
Status:	Experimental
Module:	mod_file_cache

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.

- -

Be careful with the file-path 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

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

- -

MMapFile Directive

- - - - - - -

Description:	Map a list of files into memory at startup time
Syntax:	`MMapFile file-path [file-path] ...`
Context:	server config
Status:	Experimental
Module:	mod_file_cache

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.

- -

Example

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

- -