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
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
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.
15 */
16
17/**
18 * @file ap_socache.h
19 * @brief Small object cache provider interface.
20 *
21 * @defgroup AP_SOCACHE ap_socache
22 * @ingroup  APACHE_MODS
23 * @{
24 */
25
26#ifndef AP_SOCACHE_H
27#define AP_SOCACHE_H
28
29#include "httpd.h"
30#include "ap_provider.h"
31#include "apr_pools.h"
32#include "apr_time.h"
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
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.
42 */
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?
45 */
46#define AP_SOCACHE_FLAG_NOTMPSAFE (0x0001)
47
48/** A cache instance. */
49typedef struct ap_socache_instance_t ap_socache_instance_t;
50
51/** Hints which may be passed to the init function; providers may
52 * ignore some or all of these hints. */
53struct 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;
60};
61
62/**
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
76 */
77typedef apr_status_t (ap_socache_iterator_t)(ap_socache_instance_t *instance,
78                                             server_rec *s,
79                                             void *userctx,
80                                             const unsigned char *id,
81                                             unsigned int idlen,
82                                             const unsigned char *data,
83                                             unsigned int datalen,
84                                             apr_pool_t *pool);
85
86/** A socache provider structure.  socache providers are registered
87 * with the ap_provider.h interface using the AP_SOCACHE_PROVIDER_*
88 * constants. */
89typedef struct ap_socache_provider_t {
90    /** Canonical provider name. */
91    const char *name;
92
93    /** Bitmask of AP_SOCACHE_FLAG_* flags. */
94    unsigned int flags;
95
96    /**
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.
100     *
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.
108     */
109    const char *(*create)(ap_socache_instance_t **instance, const char *arg,
110                          apr_pool_t *tmp, apr_pool_t *p);
111
112    /**
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.
120     *
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.
127     */
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);
131
132    /**
133     * Destroy a given cache instance object.
134     * @param instance The cache instance to destroy.
135     * @param s Associated server structure (for logging purposes)
136     */
137    void (*destroy)(ap_socache_instance_t *instance, server_rec *s);
138
139    /**
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.
150     */
151    apr_status_t (*store)(ap_socache_instance_t *instance, server_rec *s,
152                          const unsigned char *id, unsigned int idlen,
153                          apr_time_t expiry,
154                          unsigned char *data, unsigned int datalen,
155                          apr_pool_t *pool);
156
157    /**
158     * Retrieve a cached object.
159     *
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
169     * found
170     */
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,
174                             apr_pool_t *pool);
175
176    /**
177     * Remove an object from the cache
178     *
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.
184     */
185    apr_status_t (*remove)(ap_socache_instance_t *instance, server_rec *s,
186                           const unsigned char *id, unsigned int idlen,
187                           apr_pool_t *pool);
188
189    /**
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
193     *
194     * @param instance The cache instance
195     * @param r The request structure
196     * @param flags The AP_STATUS_* constants used (see mod_status.h)
197     */
198    void (*status)(ap_socache_instance_t *instance, request_rec *r, int flags);
199
200    /**
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
209     * found
210     */
211    apr_status_t (*iterate)(ap_socache_instance_t *instance, server_rec *s,
212                            void *userctx, ap_socache_iterator_t *iterator,
213                            apr_pool_t *pool);
214
215} ap_socache_provider_t;
216
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"
221
222/** Default provider name. */
223#define AP_SOCACHE_DEFAULT_PROVIDER "default"
224
225#ifdef __cplusplus
226}
227#endif
228
229#endif /* AP_SOCACHE_H */
230/** @} */
231