1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="socache.xml.meta">
25 <title>Shared Object Cache in Apache HTTP Server</title>
28 <p>The Shared Object Cache provides a means to share simple data
29 across all a server's workers, regardless of <a href="mpm.html">thread
30 and process models</a>. It is used where the advantages of sharing
31 data across processes outweigh the performance overhead of
32 inter-process communication.</p>
35 <section id="providers">
36 <title>Shared Object Cache Providers</title>
37 <p>The shared object cache as such is an abstraction. Four different
38 modules implement it. To use the cache, one or more of these modules
39 must be present, and configured.</p>
40 <p>The only configuration required is to select which cache provider
41 to use. This is the responsibility of modules using the cache, and
42 they enable selection using directives such as
43 <directive module="mod_cache_socache">CacheSocache</directive>,
44 <directive module="mod_authn_socache">AuthnCacheSOCache</directive>,
45 <directive module="mod_ssl">SSLSessionCache</directive>, and
46 <directive module="mod_ssl">SSLStaplingCache</directive>.</p>
47 <p>Currently available providers are:</p>
49 <dt>"dbm" (<module>mod_socache_dbm</module>)</dt>
50 <dd>This makes use of a DBM hash file.
51 The choice of underlying DBM used may be configurable
52 if the installed APR version supports multiple DBM implementations.</dd>
53 <dt>"dc" (<module>mod_socache_dc</module>)</dt>
54 <dd>This makes use of the <a href="http://www.distcache.org/">distcache</a>
55 distributed session caching libraries.</dd>
56 <dt>"memcache" (<module>mod_socache_memcache</module>)</dt>
57 <dd>This makes use of the <a href="http://memcached.org/">memcached</a>
58 high-performance, distributed memory object caching system.</dd>
59 <dt>"shmcb" (<module>mod_socache_shmcb</module>)</dt>
60 <dd>This makes use of a high-performance cyclic buffer inside a
61 shared memory segment.</dd>
64 <p>The API provides the following functions:</p>
67 <dt>const char *create(ap_socache_instance_t **instance, const char *arg,
68 apr_pool_t *tmp, apr_pool_t *p);</dt>
69 <dd>Create a session cache based on the given configuration string.
70 The instance pointer returned in the instance paramater will be
71 passed as the first argument to subsequent invocations.</dd>
73 <dt>apr_status_t init(ap_socache_instance_t *instance, const char *cname,
74 const struct ap_socache_hints *hints,
75 server_rec *s, apr_pool_t *pool)</dt>
76 <dd>Initialize the cache. The cname must be of maximum length 16
77 characters, and uniquely identifies the consumer of the cache
78 within the server; using the module name is recommended, e.g.
79 "mod_ssl-sess". This string may be used within a filesystem
80 path so use of only alphanumeric [a-z0-9_-] characters is
81 recommended. If hints is non-NULL, it gives a set of hints for
82 the provider. Return APR error code.</dd>
84 <dt>void destroy(ap_socache_instance_t *instance, server_rec *s)</dt>
85 <dd>Destroy a given cache instance object.</dd>
87 <dt>apr_status_t store(ap_socache_instance_t *instance, server_rec *s,
88 const unsigned char *id, unsigned int idlen,
90 unsigned char *data, unsigned int datalen,
91 apr_pool_t *pool)</dt>
92 <dd>Store an object in a cache instance.</dd>
94 <dt>apr_status_t retrieve(ap_socache_instance_t *instance, server_rec *s,
95 const unsigned char *id, unsigned int idlen,
96 unsigned char *data, unsigned int *datalen,
97 apr_pool_t *pool)</dt>
98 <dd>Retrieve a cached object.</dd>
100 <dt>apr_status_t remove(ap_socache_instance_t *instance, server_rec *s,
101 const unsigned char *id, unsigned int idlen,
102 apr_pool_t *pool)</dt>
103 <dd>Remove an object from the cache.</dd>
105 <dt>void status(ap_socache_instance_t *instance, request_rec *r, int flags)</dt>
106 <dd>Dump the status of a cache instance for mod_status.</dd>
108 <dt>apr_status_t iterate(ap_socache_instance_t *instance, server_rec *s,
109 void *userctx, ap_socache_iterator_t *iterator,
110 apr_pool_t *pool)</dt>
111 <dd>Dump all cached objects through an iterator callback.</dd>