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 paramater 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 Used-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);
112 /* Initialize the cache. The cname must be of maximum length 16
113 * characters, and uniquely identifies the consumer of the cache
114 * within the server; using the module name is recommended, e.g.
115 * "mod_ssl-sess". This string may be used within a filesystem
116 * path so use of only alphanumeric [a-z0-9_-] characters is
117 * recommended. If hints is non-NULL, it gives a set of hints for
118 * the provider. Return APR error code.
120 * @param instance The cache instance
121 * @param cname A unique string identifying the consumer of this API
122 * @param hints Optional hints argument describing expected cache use
123 * @param s Server structure to which the cache is associated
124 * @param pool Pool for long-lived allocations
125 * @return APR status value indicating success.
127 apr_status_t (*init)(ap_socache_instance_t *instance, const char *cname,
128 const struct ap_socache_hints *hints,
129 server_rec *s, apr_pool_t *pool);
132 * Destroy a given cache instance object.
133 * @param instance The cache instance to destroy.
134 * @param s Associated server structure (for logging purposes)
136 void (*destroy)(ap_socache_instance_t *instance, server_rec *s);
139 * Store an object in a cache instance.
140 * @param instance The cache instance
141 * @param s Associated server structure (for logging purposes)
142 * @param id Unique ID for the object; binary blob
143 * @param idlen Length of id blob
144 * @param expiry Absolute time at which the object expires
145 * @param data Data to store; binary blob
146 * @param datalen Length of data blob
147 * @param pool Pool for temporary allocations.
148 * @return APR status value.
150 apr_status_t (*store)(ap_socache_instance_t *instance, server_rec *s,
151 const unsigned char *id, unsigned int idlen,
153 unsigned char *data, unsigned int datalen,
157 * Retrieve a cached object.
158 * @param instance The cache instance
159 * @param s Associated server structure (for logging purposes)
160 * @param id Unique ID for the object; binary blob
161 * @param idlen Length of id blob
162 * @param data Output buffer to place retrievd data (binary blob)
163 * @param datalen On entry, length of data buffer; on exit, the
164 * number of bytes written to the data buffer.
165 * @param pool Pool for temporary allocations.
166 * @return APR status value; APR_NOTFOUND if the object was not
169 apr_status_t (*retrieve)(ap_socache_instance_t *instance, server_rec *s,
170 const unsigned char *id, unsigned int idlen,
171 unsigned char *data, unsigned int *datalen,
174 /* Remove an object from the cache
175 * @param instance The cache instance
176 * @param s Associated server structure (for logging purposes)
177 * @param id Unique ID for the object; binary blob
178 * @param idlen Length of id blob
179 * @param pool Pool for temporary allocations.
181 apr_status_t (*remove)(ap_socache_instance_t *instance, server_rec *s,
182 const unsigned char *id, unsigned int idlen,
185 /** Dump the status of a cache instance for mod_status. Will use
186 * the ap_r* interfaces to produce appropriate status output.
187 * XXX: ap_r* are deprecated, bad dogfood
189 * @param instance The cache instance
190 * @param r The request structure
191 * @param flags The AP_STATUS_* constants used (see mod_status.h)
193 void (*status)(ap_socache_instance_t *instance, request_rec *r, int flags);
196 * Dump all cached objects through an iterator callback.
197 * @param instance The cache instance
198 * @param s Associated server context (for processing and logging)
199 * @param userctx User defined pointer passed through to the iterator
200 * @param iterator The user provided callback function which will receive
201 * individual calls for each unexpired id/data pair
202 * @param pool Pool for temporary allocations.
203 * @return APR status value; APR_NOTFOUND if the object was not
206 apr_status_t (*iterate)(ap_socache_instance_t *instance, server_rec *s,
207 void *userctx, ap_socache_iterator_t *iterator,
210 } ap_socache_provider_t;
212 /** The provider group used to register socache providers. */
213 #define AP_SOCACHE_PROVIDER_GROUP "socache"
214 /** The provider version used to register socache providers. */
215 #define AP_SOCACHE_PROVIDER_VERSION "0"
217 /** Default provider name. */
218 #define AP_SOCACHE_DEFAULT_PROVIDER "default"
224 #endif /* AP_SOCACHE_H */