httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From minf...@apache.org
Subject svn commit: r1029587 - in /httpd/httpd/trunk/docs/manual/mod: mod_cache.xml mod_disk_cache.xml
Date Mon, 01 Nov 2010 09:50:43 GMT
Author: minfrin
Date: Mon Nov  1 09:50:42 2010
New Revision: 1029587

URL: http://svn.apache.org/viewvc?rev=1029587&view=rev
Log:
Add documentation for mod_cache and mod_disk_cache.

Modified:
    httpd/httpd/trunk/docs/manual/mod/mod_cache.xml
    httpd/httpd/trunk/docs/manual/mod/mod_disk_cache.xml

Modified: httpd/httpd/trunk/docs/manual/mod/mod_cache.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_cache.xml?rev=1029587&r1=1029586&r2=1029587&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_cache.xml (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_cache.xml Mon Nov  1 09:50:42 2010
@@ -23,7 +23,7 @@
 <modulesynopsis metafile="mod_cache.xml.meta">
 
 <name>mod_cache</name>
-<description>Content cache keyed to URIs.</description>
+<description>RFC 2616 compliant HTTP caching filter.</description>
 <status>Extension</status>
 <sourcefile>mod_cache.c</sourcefile>
 <identifier>cache_module</identifier>
@@ -39,18 +39,81 @@
     variable.</note>  
 
     <p><module>mod_cache</module> implements an <a
-    href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> compliant HTTP
-    content cache that can be used to cache either local or proxied content.
-    <module>mod_cache</module> requires the services of one or more storage
-    management modules. One storage management module is included in
+    href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> compliant
+    <strong>HTTP content caching filter</strong>, with support for the caching
+    of content negotiated responses containing the Vary header.</p>
+
+    <p>RFC 2616 compliant caching provides a mechanism to verify whether
+    stale or expired content is still fresh, and can represent a significant
+    performance boost when the origin server supports <strong>conditional
+    requests</strong> by honouring the
+    <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26">If-None-Match</a>
+    HTTP request header. Content is only regenerated from scratch when the content
+    has changed, and not when the cached entry expires.</p>
+
+    <p>As a filter, <module>mod_cache</module> can be placed in front of
+    content originating from any handler, including <strong>flat
+    files</strong> (served from a slow disk cached on a fast disk), the output
+    of a <strong>CGI script</strong> or <strong>dynamic content
+    generator</strong>, or content <strong>proxied from another
+    server</strong>.</p>
+
+    <p>In the default configuration, <module>mod_cache</module> inserts
the
+    caching filter as far forward as possible within the filter stack,
+    utilising the <strong>quick handler</strong> to bypass all per request
+    processing when returning content to the client. In this mode of
+    operation, <module>mod_cache</module> may be thought of as a caching
+    proxy server bolted to the front of the webserver, while running within
+    the webserver itself.</p>
+
+    <p>When the quick handler is switched off using the
+    <directive module="mod_cache">CacheQuickHandler</directive> directive,
+    it becomes possible to insert the <strong>CACHE</strong> filter at a
+    point in the filter stack chosen by the administrator. This provides the
+    opportunity to cache content before that content is personalised by the
+    <module>mod_include</module> filter, or optionally compressed by the
+    <module>mod_deflate</module> filter.</p>
+
+    <p>Under normal operation, <module>mod_cache</module> will respond
to
+    and can be controlled by the
+    <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">Cache-Control</a>
+    and
+    <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.32">Pragma</a>
+    headers sent from a client in a request, or from a
+    server within a response. Under exceptional circumstances,
+    <module>mod_cache</module> can be configured to override these headers
+    and force site specific behaviour, however such behaviour will be limited
+    to this cache only, and will not affect the operation of other caches
+    that may exist between the client and server, and as a result is not
+    recommended unless strictly necessary.</p>
+
+    <p>RFC 2616 allows for the cache to return stale data while the existing
+    stale entry is refreshed from the origin server, and this is supported
+    by <module>mod_cache</module> when the
+    <directive module="mod_cache">CacheLock</directive> directive is suitably
+    configured. Such responses will contain a
+    <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.46">Warning</a>
+    HTTP header with a 110 response code. RFC 2616 also allows a cache to return
+    stale data when the attempt made to refresh the stale data returns an
+    error 500 or above, and this behaviour is supported by default by
+    <module>mod_cache</module>. Such responses will contain a
+    <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.46">Warning</a>
+    HTTP header with a 111 response code.</p>
+
+    <p><module>mod_cache</module> requires the services of one or more
+    storage management modules. One storage management module is included in
     the base Apache distribution:</p>
     <dl>
     <dt><module>mod_disk_cache</module></dt>
-    <dd>implements a disk based storage manager.</dd>
+    <dd>Implements a disk based storage manager. Headers and bodies are
+    stored separately on disk, in a directory structure derived from the
+    md5 hash of the cached URL. Multiple content negotiated responses can
+    be stored concurrently, however the caching of partial content is not
+    supported by this module. The <program>htcacheclean</program> tool is
+    provided to list cached URLs, remove cached URLs, or to maintain the size
+    of the disk cache within size and inode limits.</dd>
     </dl>
 
-    <p>Content is stored in and retrieved from the cache using URI based keys. Content
with
-    access protection is not cached.</p>
     <p>Further details, discussion, and examples, are provided in the
     <a href="../caching.html">Caching Guide</a>.</p>
 </summary>
@@ -167,7 +230,7 @@
   cache performance available.</p>
   
   <p>In this mode, the cache <strong>bolts onto</strong> the front of the
server,
-  acting as if a free standing RFC2616 caching proxy had been placed in front of
+  acting as if a free standing RFC 2616 caching proxy had been placed in front of
   the server.</p>
   
   <p>While this mode offers the best performance, the administrator may find that

Modified: httpd/httpd/trunk/docs/manual/mod/mod_disk_cache.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_disk_cache.xml?rev=1029587&r1=1029586&r2=1029587&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_disk_cache.xml (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_disk_cache.xml Mon Nov  1 09:50:42 2010
@@ -23,21 +23,32 @@
 <modulesynopsis metafile="mod_disk_cache.xml.meta">
 
 <name>mod_disk_cache</name>
-<description>Content cache storage manager keyed to URIs</description>
+<description>Disk based storage module for the HTTP caching filter.</description>
 <status>Extension</status>
 <sourcefile>mod_disk_cache.c</sourcefile>
 <identifier>disk_cache_module</identifier>
 
 <summary>
     <p><module>mod_disk_cache</module> implements a disk based storage
-    manager. It is primarily of use in conjunction with
-    <module>mod_cache</module>.</p>
+    manager for <module>mod_cache</module>.</p>
 
-    <p>Content is stored in and retrieved from the cache using URI based
-    keys. Content with access protection is not cached.</p>
-
-    <p><program>htcacheclean</program> can be used to maintain the cache
-       size at a maximum level.</p>
+    <p>The headers and bodies of cached responses are stored separately on
+    disk, in a directory structure derived from the md5 hash of the cached
+    URL.</p>
+
+    <p>Multiple content negotiated responses can be stored concurrently,
+    however the caching of partial content is not yet supported by this
+    module.</p>
+
+    <p>Atomic cache updates to both header and body files are achieved
+    without the need for locking by storing the device and inode numbers of
+    the body file within the header file. This has the side effect that
+    cache entries manually moved into the cache will be ignored.</p>
+
+    <p>The <program>htcacheclean</program> tool is provided to list cached
+    URLs, remove cached URLs, or to maintain the size of the disk cache
+    within size and/or inode limits. The tool can be run on demand, or
+    can be daemonized to offer continuous monitoring of directory sizes.</p>
 
     <note><title>Note:</title>
       <p><module>mod_disk_cache</module> requires the services of



Mime
View raw message