include/ap_socache.h

   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
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /** If this flag is set, the store/retrieve/remove/status interfaces
  38  * of the provider are NOT safe to be called concurrently from
  39  * multiple processes or threads, and an external global mutex must be
  40  * used to serialize access to the provider. */
  41 #define AP_SOCACHE_FLAG_NOTMPSAFE (0x0001)
  42
  43 /** A cache instance. */
  44 typedef struct ap_socache_instance_t ap_socache_instance_t;
  45
  46 /** Hints which may be passed to the init function; providers may
  47  * ignore some or all of these hints. */
  48 struct ap_socache_hints {
  49     /** Approximate average length of IDs: */
  50     apr_size_t avg_id_len;
  51     /** Approximate average size of objects: */
  52     apr_size_t avg_obj_size;
  53     /** Interval (in seconds) after which an expiry run is
  54      * necessary. */
  55     time_t expiry_interval;
  56 };
  57
  58 /** A socache provider structure.  socache providers are registered
  59  * with the ap_provider.h interface using the AP_SOCACHE_PROVIDER_*
  60  * constants. */
  61 typedef struct ap_socache_provider_t {
  62     /** Canonical provider name: */
  63     const char *name;
  64
  65     /** Bitmask of AP_SOCACHE_FLAG_* flags: */
  66     unsigned int flags;
  67
  68     /**
  69      * 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.
  72      *
  73      * @param instance Output parameter to which instance object is written.
  74      * @param arg Used-specified configuration string.  May be NULL to
  75      *        force use of defaults.
  76      * @param tmp Pool to be used for any temporary allocations
  77      * @param p Pool to be use for any allocations lasting as long as
  78      * the created instance
  79      * @return NULL on success, or an error string on failure.
  80      */
  81     const char *(*create)(ap_socache_instance_t **instance, const char *arg,
  82                           apr_pool_t *tmp, apr_pool_t *p);
  83
  84     /* Initialize the cache.  The cname must be of maximum length 16
  85      * characters, and uniquely identifies the consumer of the cache
  86      * within the server; using the module name is recommended, e.g.
  87      * "mod_ssl-sess".  This string may be used within a filesystem
  88      * path so use of only alphanumeric [a-z0-9_-] characters is
  89      * recommended.  If hints is non-NULL, it gives a set of hints for
  90      * the provider.  Return APR error code.
  91      *
  92      * @param instance The cache instance
  93      * @param cname A unique string identifying the consumer of this API
  94      * @param hints Optional hints argument describing expected cache use
  95      * @param s Server structure to which the cache is associated
  96      * @param pool Pool for long-lived allocations
  97      * @return APR status value indicating success.
  98      */
  99     apr_status_t (*init)(ap_socache_instance_t *instance, const char *cname,
 100                          const struct ap_socache_hints *hints,
 101                          server_rec *s, apr_pool_t *pool);
 102
 103     /**
 104      * Destroy a given cache instance object.
 105      * @param instance The cache instance to destroy.
 106      * @param s Associated server structure (for logging purposes)
 107      */
 108     void (*destroy)(ap_socache_instance_t *instance, server_rec *s);
 109
 110     /**
 111      * Store an object in a cache instance.
 112      * @param instance The cache instance
 113      * @param s Associated server structure (for logging purposes)
 114      * @param id Unique ID for the object; binary blob
 115      * @param idlen Length of id blob
 116      * @param expiry Absolute time at which the object expires
 117      * @param data Data to store; binary blob
 118      * @param datalen Length of data blob
 119      * @param pool Pool for temporary allocations.
 120      * @return APR status value.
 121      */
 122     apr_status_t (*store)(ap_socache_instance_t *instance, server_rec *s,
 123                           const unsigned char *id, unsigned int idlen,
 124                           time_t expiry,
 125                           unsigned char *data, unsigned int datalen,
 126                           apr_pool_t *pool);
 127
 128     /**
 129      * Retrieve a cached object.
 130      * @param instance The cache instance
 131      * @param s Associated server structure (for logging purposes)
 132      * @param id Unique ID for the object; binary blob
 133      * @param idlen Length of id blob
 134      * @param data Output buffer to place retrievd data (binary blob)
 135      * @param datalen On entry, length of data buffer; on exit, the
 136      * number of bytes written to the data buffer.
 137      * @param pool Pool for temporary allocations.
 138      * @return APR status value; APR_NOTFOUND if the object was not
 139      * found
 140      */
 141     apr_status_t (*retrieve)(ap_socache_instance_t *instance, server_rec *s,
 142                              const unsigned char *id, unsigned int idlen,
 143                              unsigned char *data, unsigned int *datalen,
 144                              apr_pool_t *pool);
 145
 146     /* Remove an object from the cache
 147      * @param instance The cache instance
 148      * @param s Associated server structure (for logging purposes)
 149      * @param id Unique ID for the object; binary blob
 150      * @param idlen Length of id blob
 151      * @param pool Pool for temporary allocations.
 152      */
 153     apr_status_t (*remove)(ap_socache_instance_t *instance, server_rec *s,
 154                            const unsigned char *id, unsigned int idlen,
 155                            apr_pool_t *pool);
 156
 157     /** Dump the status of a cache instance for mod_status.  Will use
 158      * the ap_r* interfaces to produce appropriate status output.
 159      *
 160      * @param instance The cache instance
 161      * @param r The request structure
 162      * @param flags The AP_STATUS_* constants used (see mod_status.h)
 163      */
 164     void (*status)(ap_socache_instance_t *instance, request_rec *r, int flags);
 165 } ap_socache_provider_t;
 166
 167 /** The provider group used to register socache providers. */
 168 #define AP_SOCACHE_PROVIDER_GROUP "socache"
 169 /** The provider version used to register socache providers. */
 170 #define AP_SOCACHE_PROVIDER_VERSION "0"
 171
 172 /** Default provider name. */
 173 #define AP_SOCACHE_DEFAULT_PROVIDER "default"
 174
 175 #ifdef __cplusplus
 176 }
 177 #endif
 178
 179 #endif /* AP_SOCACHE_H */
 180 /** @} */