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