granicus.if.org Git - apache/blob - docs/manual/mod/mod_mem_cache.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $Revision: 1.9 $ -->
   5
   6 <!--
   7  Copyright 2002-2004 The Apache Software Foundation
   8
   9  Licensed under the Apache License, Version 2.0 (the "License");
  10  you may not use this file except in compliance with the License.
  11  You may obtain a copy of the License at
  12
  13      http://www.apache.org/licenses/LICENSE-2.0
  14
  15  Unless required by applicable law or agreed to in writing, software
  16  distributed under the License is distributed on an "AS IS" BASIS,
  17  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  See the License for the specific language governing permissions and
  19  limitations under the License.
  20 -->
  21
  22 <modulesynopsis metafile="mod_mem_cache.xml.meta">
  23
  24 <name>mod_mem_cache</name>
  25 <description>Content cache keyed to URIs</description>
  26 <status>Experimental</status>
  27 <sourcefile>mod_mem_cache.c</sourcefile>
  28 <identifier>mem_cache_module</identifier>
  29
  30 <summary>
  31     <note type="warning">
  32       This module is experimental. Documentation is still under
  33       development...
  34     </note>
  35
  36     <p>This module <em>requires</em> the service of <module
  37     >mod_cache</module>. It acts as a support module for <module
  38     >mod_cache</module> and provides a memory based storage manager.
  39     <module>mod_mem_cache</module> can be configured to operate in two
  40     modes: caching open file descriptors or caching objects in heap storage.
  41     <module>mod_mem_cache</module> is most useful when used to cache locally
  42     generated content or to cache backend server content for <module
  43     >mod_proxy</module> configured for <directive module="mod_proxy"
  44     >ProxyPass</directive> (aka <dfn>reverse proxy</dfn>).</p>
  45
  46     <p>Content is stored in and retrieved from the cache using URI based
  47     keys. Content with access protection is not cached.</p>
  48 </summary>
  49 <seealso><module>mod_cache</module></seealso>
  50 <seealso><module>mod_disk_cache</module></seealso>
  51
  52 <directivesynopsis>
  53 <name>MCacheSize</name>
  54 <description>The maximum amount of memory used by the cache in
  55 KBytes</description>
  56 <syntax>MCacheSize <var>KBytes</var></syntax>
  57 <default>MCacheSize 100</default>
  58 <contextlist><context>server config</context></contextlist>
  59
  60 <usage>
  61     <p>The <directive>MCacheSize</directive> directive sets the maximum
  62     amount of memory to be used by the cache, in KBytes (1024-byte units).
  63     If a new object needs to be inserted in the cache and the size of the
  64     object is greater than the remaining memory, objects will be removed
  65     until the new object can be cached. The object to be removed is
  66     selected using the algorithm specified by <directive
  67     module="mod_mem_cache">MCacheRemovalAlgorithm</directive>.</p>
  68
  69     <example><title>Example</title>
  70       MCacheSize 700000
  71     </example>
  72
  73     <note><title>Note</title>
  74       <p>The <directive>MCacheSize</directive> value must be greater than
  75       the value specified by the <directive module="mod_mem_cache"
  76       >MCacheMaxObjectSize</directive> directive.</p>
  77     </note>
  78 </usage>
  79 </directivesynopsis>
  80
  81 <directivesynopsis>
  82 <name>MCacheMaxObjectCount</name>
  83 <description>The maximum number of objects allowed to be placed in the
  84 cache</description>
  85 <syntax>MCacheMaxObjectCount <var>value</var></syntax>
  86 <default>MCacheMaxObjectCount 1009</default>
  87 <contextlist><context>server config</context></contextlist>
  88
  89 <usage>
  90     <p>The <directive>MCacheMaxObjectCount</directive> directive sets the
  91     maximum number of objects to be cached. The value is used to create the
  92     open hash table. If a new object needs to be inserted in the cache and
  93     the maximum number of objects has been reached, an object will be
  94     removed to allow the new object to be cached. The object to be removed
  95     is selected using the algorithm specified by <directive
  96     module="mod_mem_cache">MCacheRemovalAlgorithm</directive>.</p>
  97
  98     <example><title>Example</title>
  99       MCacheMaxObjectCount 13001
 100     </example>
 101 </usage>
 102 </directivesynopsis>
 103
 104 <directivesynopsis>
 105 <name>MCacheMinObjectSize</name>
 106 <description>The minimum size (in bytes) of a document to be allowed in the
 107 cache</description>
 108 <syntax>MCacheMinObjectSize <var>bytes</var></syntax>
 109 <default>MCacheMinObjectSize 0</default>
 110 <contextlist><context>server config</context></contextlist>
 111
 112 <usage>
 113     <p>The <directive>MCacheMinObjectSize</directive> directive sets the
 114     minimum size in bytes of a document for it to be considered
 115     cacheable.</p>
 116
 117     <example><title>Example</title>
 118       MCacheMinObjectSize 10000
 119     </example>
 120 </usage>
 121 </directivesynopsis>
 122
 123 <directivesynopsis>
 124 <name>MCacheMaxObjectSize</name>
 125 <description>The maximum size (in bytes) of a document allowed in the
 126 cache</description>
 127 <syntax>MCacheMaxObjectSize <var>bytes</var></syntax>
 128 <default>MCacheMaxObjectSize 10000</default>
 129 <contextlist><context>server config</context></contextlist>
 130
 131 <usage>
 132     <p>The <directive>MCacheMaxObjectSize</directive> directive sets the
 133     maximum allowable size, in bytes, of a document for it to be considered
 134     cacheable.</p>
 135
 136     <example><title>Example</title>
 137       MCacheMaxObjectSize 6400000
 138     </example>
 139
 140     <note><title>Note</title>
 141       <p>The value of <directive>MCacheMaxObjectSize</directive> must be
 142       greater than the value specified by the <directive
 143       module="mod_mem_cache">MCacheMinObjectSize</directive> directive.</p>
 144     </note>
 145 </usage>
 146 </directivesynopsis>
 147
 148 <directivesynopsis>
 149 <name>MCacheRemovalAlgorithm</name>
 150 <description>The algorithm used to select documents for removal from the
 151 cache</description>
 152 <syntax>MCacheRemovalAlgorithm LRU|GDSF</syntax>
 153 <default>MCacheRemovalAlgorithm GDSF</default>
 154 <contextlist><context>server config</context></contextlist>
 155
 156 <usage>
 157     <p>The <directive>MCacheRemovalAlgorithm</directive> directive specifies
 158     the algorithm used to select documents for removal from the cache.
 159     Two choices are available:</p>
 160
 161     <dl>
 162       <dt><code>LRU</code> (Least Recently Used)</dt>
 163       <dd><code>LRU</code> removes the documents that have not been accessed
 164       for the longest time.</dd>
 165
 166       <dt><code>GDSF</code> (GreadyDual-Size)</dt>
 167       <dd><code>GDSF</code> assigns a priority to cached documents based
 168       on the cost of a cache miss and the size of the document. Documents
 169       with the lowest priority are removed first.</dd>
 170     </dl>
 171
 172     <example><title>Example</title>
 173       MCacheRemovalAlgorithm GDSF<br />
 174       MCacheRemovalAlgorithm LRU
 175     </example>
 176 </usage>
 177 </directivesynopsis>
 178
 179 <directivesynopsis>
 180 <name>MCacheMaxStreamingBuffer</name>
 181 <description>Maximum amount of a streamed response to buffer in memory
 182 before declaring the response uncacheable</description>
 183 <syntax>MCacheMaxStreamingBuffer <var>size_in_bytes</var></syntax>
 184 <default>MCacheMaxStreamingBuffer the smaller of 100000 or MCacheMaxObjectSize</default>
 185 <contextlist><context>server config</context>
 186 </contextlist>
 187
 188 <usage>
 189     <p>The <directive>MCacheMaxStreamingBuffer</directive> directive
 190     specifies the maximum number of bytes of a streamed response to
 191     buffer before deciding that the response is too big to cache.
 192     A streamed response is one in which the entire content is not
 193     immediately available and in which the <code>Content-Length</code>
 194     may not be known. Sources of streaming responses include proxied
 195     responses and the output of CGI scripts. By default, a streamed
 196     response will <em>not</em> be cached unless it has a
 197     <code>Content-Length</code> header. The reason for this is to
 198     avoid using a large amount of memory to buffer a partial response
 199     that might end up being too large to fit in the cache.
 200     The <directive>MCacheMaxStreamingBuffer</directive> directive allows
 201     buffering of streamed responses that don't contain a
 202     <code>Content-Length</code> up to the specified maximum amount of
 203     space. If the maximum buffer space is reached, the buffered
 204     content is discarded and the attempt to cache is abandoned.</p>
 205
 206     <note><title>Note:</title>
 207       <p>Using a nonzero value for <directive>MCacheMaxStreamingBuffer</directive>
 208       will not delay the transmission of the response to the client.
 209       As soon as <module>mod_mem_cache</module> copies a block of streamed
 210       content into a buffer, it sends the block on to the next output
 211       filter for delivery to the client.</p>
 212     </note>
 213
 214     <example>
 215       # Enable caching of streamed responses up to 64KB:<br />
 216       MCacheMaxStreamingBuffer 65536
 217     </example>
 218 </usage>
 219 </directivesynopsis>
 220
 221 </modulesynopsis>