ap_socache.h 9.17 KB
Newer Older
powelld's avatar
powelld committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file ap_socache.h
 * @brief Small object cache provider interface.
 *
 * @defgroup AP_SOCACHE ap_socache
 * @ingroup  APACHE_MODS
 * @{
 */

#ifndef AP_SOCACHE_H
#define AP_SOCACHE_H

#include "httpd.h"
#include "ap_provider.h"
#include "apr_pools.h"
#include "apr_time.h"

#ifdef __cplusplus
extern "C" {
#endif

/** If this flag is set, the store/retrieve/remove/status interfaces
 * of the provider are NOT safe to be called concurrently from
 * multiple processes or threads, and an external global mutex must be
 * used to serialize access to the provider.
 */
/* XXX: Even if store/retrieve/remove is atomic, isn't it useful to note
 * independently that status and iterate may or may not be?
 */
#define AP_SOCACHE_FLAG_NOTMPSAFE (0x0001)

/** A cache instance. */
typedef struct ap_socache_instance_t ap_socache_instance_t;

/** Hints which may be passed to the init function; providers may
 * ignore some or all of these hints. */
struct ap_socache_hints {
    /** Approximate average length of IDs: */
    apr_size_t avg_id_len;
    /** Approximate average size of objects: */
    apr_size_t avg_obj_size;
    /** Suggested interval between expiry cleanup runs; */
    apr_interval_time_t expiry_interval;
};

/**
 * Iterator callback prototype for the ap_socache_provider_t->iterate() method
 * @param instance The cache instance
 * @param s Associated server context (for logging)
 * @param userctx User defined pointer passed from the iterator call
 * @param id Unique ID for the object (binary blob)
 * with a trailing null char for convenience
 * @param idlen Length of id blob
 * @param data Output buffer to place retrieved data (binary blob)
 * with a trailing null char for convenience
 * @param datalen Length of data buffer
 * @param pool Pool for temporary allocations
 * @return APR status value; return APR_SUCCESS or the iteration will halt;
 * this value is returned to the ap_socache_provider_t->iterate() caller
 */
typedef apr_status_t (ap_socache_iterator_t)(ap_socache_instance_t *instance,
                                             server_rec *s,
                                             void *userctx,
                                             const unsigned char *id,
                                             unsigned int idlen,
                                             const unsigned char *data,
                                             unsigned int datalen,
                                             apr_pool_t *pool);

/** A socache provider structure.  socache providers are registered
 * with the ap_provider.h interface using the AP_SOCACHE_PROVIDER_*
 * constants. */
typedef struct ap_socache_provider_t {
    /** Canonical provider name. */
    const char *name;

    /** Bitmask of AP_SOCACHE_FLAG_* flags. */
    unsigned int flags;

    /**
     * Create a session cache based on the given configuration string.
     * The instance pointer returned in the instance parameter will be
     * passed as the first argument to subsequent invocations.
     *
     * @param instance Output parameter to which instance object is written.
     * @param arg User-specified configuration string.  May be NULL to
     *        force use of defaults.
     * @param tmp Pool to be used for any temporary allocations
     * @param p Pool to be use for any allocations lasting as long as
     * the created instance
     * @return NULL on success, or an error string on failure.
     */
    const char *(*create)(ap_socache_instance_t **instance, const char *arg,
                          apr_pool_t *tmp, apr_pool_t *p);

    /**
     * Initialize the cache.  The cname must be of maximum length 16
     * characters, and uniquely identifies the consumer of the cache
     * within the server; using the module name is recommended, e.g.
     * "mod_ssl-sess".  This string may be used within a filesystem
     * path so use of only alphanumeric [a-z0-9_-] characters is
     * recommended.  If hints is non-NULL, it gives a set of hints for
     * the provider.  Returns APR error code.
     *
     * @param instance The cache instance
     * @param cname A unique string identifying the consumer of this API
     * @param hints Optional hints argument describing expected cache use
     * @param s Server structure to which the cache is associated
     * @param pool Pool for long-lived allocations
     * @return APR status value indicating success.
     */
    apr_status_t (*init)(ap_socache_instance_t *instance, const char *cname,
                         const struct ap_socache_hints *hints,
                         server_rec *s, apr_pool_t *pool);

    /**
     * Destroy a given cache instance object.
     * @param instance The cache instance to destroy.
     * @param s Associated server structure (for logging purposes)
     */
    void (*destroy)(ap_socache_instance_t *instance, server_rec *s);

    /**
     * Store an object in a cache instance.
     * @param instance The cache instance
     * @param s Associated server structure (for logging purposes)
     * @param id Unique ID for the object; binary blob
     * @param idlen Length of id blob
     * @param expiry Absolute time at which the object expires
     * @param data Data to store; binary blob
     * @param datalen Length of data blob
     * @param pool Pool for temporary allocations.
     * @return APR status value.
     */
    apr_status_t (*store)(ap_socache_instance_t *instance, server_rec *s,
                          const unsigned char *id, unsigned int idlen,
                          apr_time_t expiry,
                          unsigned char *data, unsigned int datalen,
                          apr_pool_t *pool);

    /**
     * Retrieve a cached object.
     * 
     * @param instance The cache instance
     * @param s Associated server structure (for logging purposes)
     * @param id Unique ID for the object; binary blob
     * @param idlen Length of id blob
     * @param data Output buffer to place retrievd data (binary blob)
     * @param datalen On entry, length of data buffer; on exit, the
     * number of bytes written to the data buffer.
     * @param pool Pool for temporary allocations.
     * @return APR status value; APR_NOTFOUND if the object was not
     * found
     */
    apr_status_t (*retrieve)(ap_socache_instance_t *instance, server_rec *s,
                             const unsigned char *id, unsigned int idlen,
                             unsigned char *data, unsigned int *datalen,
                             apr_pool_t *pool);

    /**
     * Remove an object from the cache
     *
     * @param instance The cache instance
     * @param s Associated server structure (for logging purposes)
     * @param id Unique ID for the object; binary blob
     * @param idlen Length of id blob
     * @param pool Pool for temporary allocations.
     */
    apr_status_t (*remove)(ap_socache_instance_t *instance, server_rec *s,
                           const unsigned char *id, unsigned int idlen,
                           apr_pool_t *pool);

    /** 
     * Dump the status of a cache instance for mod_status.  Will use
     * the ap_r* interfaces to produce appropriate status output.
     * XXX: ap_r* are deprecated, bad dogfood
     *
     * @param instance The cache instance
     * @param r The request structure
     * @param flags The AP_STATUS_* constants used (see mod_status.h)
     */
    void (*status)(ap_socache_instance_t *instance, request_rec *r, int flags);

    /**
     * Dump all cached objects through an iterator callback.
     * @param instance The cache instance
     * @param s Associated server context (for processing and logging)
     * @param userctx User defined pointer passed through to the iterator
     * @param iterator The user provided callback function which will receive
     * individual calls for each unexpired id/data pair
     * @param pool Pool for temporary allocations.
     * @return APR status value; APR_NOTFOUND if the object was not
     * found
     */
    apr_status_t (*iterate)(ap_socache_instance_t *instance, server_rec *s,
                            void *userctx, ap_socache_iterator_t *iterator,
                            apr_pool_t *pool);

} ap_socache_provider_t;

/** The provider group used to register socache providers. */
#define AP_SOCACHE_PROVIDER_GROUP "socache"
/** The provider version used to register socache providers. */
#define AP_SOCACHE_PROVIDER_VERSION "0"

/** Default provider name. */
#define AP_SOCACHE_DEFAULT_PROVIDER "default"

#ifdef __cplusplus
}
#endif

#endif /* AP_SOCACHE_H */
/** @} */