1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements. See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
19 * @brief Small object cache provider interface.
21 * @defgroup AP_SOCACHE ap_socache
22 * @ingroup APACHE_MODS
30 #include "ap_provider.h"
31 #include "apr_pools.h"
38 /** If this flag is set, the store/retrieve/remove/status interfaces
39 * of the provider are NOT safe to be called concurrently from
40 * multiple processes or threads, and an external global mutex must be
41 * used to serialize access to the provider.
43 /* XXX: Even if store/retrieve/remove is atomic, isn't it useful to note
44 * independently that status and iterate may or may not be?
46 #define AP_SOCACHE_FLAG_NOTMPSAFE (0x0001)
48 /** A cache instance. */
49 typedef struct ap_socache_instance_t ap_socache_instance_t;
51 /** Hints which may be passed to the init function; providers may
52 * ignore some or all of these hints. */
53 struct ap_socache_hints {
54 /** Approximate average length of IDs: */
55 apr_size_t avg_id_len;
56 /** Approximate average size of objects: */
57 apr_size_t avg_obj_size;
58 /** Suggested interval between expiry cleanup runs; */
59 apr_interval_time_t expiry_interval;
63 * Iterator callback prototype for the ap_socache_provider_t->iterate() method
64 * @param instance The cache instance
65 * @param s Associated server context (for logging)
66 * @param userctx User defined pointer passed from the iterator call
67 * @param id Unique ID for the object (binary blob)
68 * with a trailing null char for convenience
69 * @param idlen Length of id blob
70 * @param data Output buffer to place retrieved data (binary blob)
71 * with a trailing null char for convenience
72 * @param datalen Length of data buffer
73 * @param pool Pool for temporary allocations
74 * @return APR status value; return APR_SUCCESS or the iteration will halt;
75 * this value is returned to the ap_socache_provider_t->iterate() caller
77 typedef apr_status_t (ap_socache_iterator_t)(ap_socache_instance_t *instance,
80 const unsigned char *id,
82 const unsigned char *data,
86 /** A socache provider structure. socache providers are registered
87 * with the ap_provider.h interface using the AP_SOCACHE_PROVIDER_*
89 typedef struct ap_socache_provider_t {
90 /** Canonical provider name. */
93 /** Bitmask of AP_SOCACHE_FLAG_* flags. */
97 * Create a session cache based on the given configuration string.
98 * The instance pointer returned in the instance parameter will be
99 * passed as the first argument to subsequent invocations.
101 * @param instance Output parameter to which instance object is written.
102 * @param arg User-specified configuration string. May be NULL to
103 * force use of defaults.
104 * @param tmp Pool to be used for any temporary allocations
105 * @param p Pool to be use for any allocations lasting as long as
106 * the created instance
107 * @return NULL on success, or an error string on failure.
109 const char *(*create)(ap_socache_instance_t **instance, const char *arg,
110 apr_pool_t *tmp, apr_pool_t *p);
113 * Initialize the cache. The cname must be of maximum length 16
114 * characters, and uniquely identifies the consumer of the cache
115 * within the server; using the module name is recommended, e.g.
116 * "mod_ssl-sess". This string may be used within a filesystem
117 * path so use of only alphanumeric [a-z0-9_-] characters is
118 * recommended. If hints is non-NULL, it gives a set of hints for
119 * the provider. Returns APR error code.
121 * @param instance The cache instance
122 * @param cname A unique string identifying the consumer of this API
123 * @param hints Optional hints argument describing expected cache use
124 * @param s Server structure to which the cache is associated
125 * @param pool Pool for long-lived allocations
126 * @return APR status value indicating success.
128 apr_status_t (*init)(ap_socache_instance_t *instance, const char *cname,
129 const struct ap_socache_hints *hints,
130 server_rec *s, apr_pool_t *pool);
133 * Destroy a given cache instance object.
134 * @param instance The cache instance to destroy.
135 * @param s Associated server structure (for logging purposes)
137 void (*destroy)(ap_socache_instance_t *instance, server_rec *s);
140 * Store an object in a cache instance.
141 * @param instance The cache instance
142 * @param s Associated server structure (for logging purposes)
143 * @param id Unique ID for the object; binary blob
144 * @param idlen Length of id blob
145 * @param expiry Absolute time at which the object expires
146 * @param data Data to store; binary blob
147 * @param datalen Length of data blob
148 * @param pool Pool for temporary allocations.
149 * @return APR status value.
151 apr_status_t (*store)(ap_socache_instance_t *instance, server_rec *s,
152 const unsigned char *id, unsigned int idlen,
154 unsigned char *data, unsigned int datalen,
158 * Retrieve a cached object.
160 * @param instance The cache instance
161 * @param s Associated server structure (for logging purposes)
162 * @param id Unique ID for the object; binary blob
163 * @param idlen Length of id blob
164 * @param data Output buffer to place retrievd data (binary blob)
165 * @param datalen On entry, length of data buffer; on exit, the
166 * number of bytes written to the data buffer.
167 * @param pool Pool for temporary allocations.
168 * @return APR status value; APR_NOTFOUND if the object was not
171 apr_status_t (*retrieve)(ap_socache_instance_t *instance, server_rec *s,
172 const unsigned char *id, unsigned int idlen,
173 unsigned char *data, unsigned int *datalen,
177 * Remove an object from the cache
179 * @param instance The cache instance
180 * @param s Associated server structure (for logging purposes)
181 * @param id Unique ID for the object; binary blob
182 * @param idlen Length of id blob
183 * @param pool Pool for temporary allocations.
185 apr_status_t (*remove)(ap_socache_instance_t *instance, server_rec *s,
186 const unsigned char *id, unsigned int idlen,
190 * Dump the status of a cache instance for mod_status. Will use
191 * the ap_r* interfaces to produce appropriate status output.
192 * XXX: ap_r* are deprecated, bad dogfood
194 * @param instance The cache instance
195 * @param r The request structure
196 * @param flags The AP_STATUS_* constants used (see mod_status.h)
198 void (*status)(ap_socache_instance_t *instance, request_rec *r, int flags);
201 * Dump all cached objects through an iterator callback.
202 * @param instance The cache instance
203 * @param s Associated server context (for processing and logging)
204 * @param userctx User defined pointer passed through to the iterator
205 * @param iterator The user provided callback function which will receive
206 * individual calls for each unexpired id/data pair
207 * @param pool Pool for temporary allocations.
208 * @return APR status value; APR_NOTFOUND if the object was not
211 apr_status_t (*iterate)(ap_socache_instance_t *instance, server_rec *s,
212 void *userctx, ap_socache_iterator_t *iterator,
215 } ap_socache_provider_t;
217 /** The provider group used to register socache providers. */
218 #define AP_SOCACHE_PROVIDER_GROUP "socache"
219 /** The provider version used to register socache providers. */
220 #define AP_SOCACHE_PROVIDER_VERSION "0"
222 /** Default provider name. */
223 #define AP_SOCACHE_DEFAULT_PROVIDER "default"
229 #endif /* AP_SOCACHE_H */