httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chris Darroch <>
Subject Re: [PATCH] ap_socache.h & mod_socache_*
Date Thu, 06 Mar 2008 22:33:12 GMT
Hi --

   This looks great!  Some semi-random thoughts, dealing just with
the main header file.

   I was a little puzzled by the name "socache" because I assumed
"so" meant "shared object", like mod_so, until I read the code comments.
I wondered if it was true that people would only use this kind of
interface to store small objects -- I won't, for one.  (We can
migrate our session cache to this interface and we cram all kinds of
data in there.)

   Also, I wondered if the term "cache" was necessarily accurate, if
some providers allow unlimited persistent storage (DBM, DBD, etc.)
I'm hoping to be able to store things with expiry=0 to mean "persist as
long as possible".  "Cache" also overlaps with the mod_cache and
friends which implement something rather different.

   With those thoughts in mind, some other possible names presented
themselves -- perhaps grouped under modules/foo, where foo is the
name of choice?  I thought of map, dict, store, table, and hash,
possibly with a "d" (data, distributed) or "s" (shared) prefix, e.g.,
mod_dtable, mod_dtable_distcache, etc.  I kind of like mod_dict myself,
or mod_dtable or mod_dmap.

   Should the expiry argument to store() be an apr_interval_time_t
or an apr_time_t?  I'd love to be allowed 0 to mean "don't expire" too.
And perhaps apr_size_t for the key and value lengths?

   Is there a particular reason for the store(), retrieve(), delete()
names?  APR hashes use get/set (set NULL to delete), tables use
get/set/unset, and DBM uses store/fetch/delete.  I'd sort of be
inclined toward following the DBM names and changing retrieve() to
fetch().  Thoughts?

   I also wanted to suggest some different/additional flags; I've
tried to describe their meaning in the proposed header file below.

   Thanks again for tackling this work -- let me know if I can help.


 * @file ap_dict.h
 * @brief Shared data dictionary provider interface.
 * @defgroup AP_DICT ap_dict
 * @ingroup  APACHE_MODS
 * @{

#ifndef AP_DICT_H
#define AP_DICT_H 
#include "httpd.h"
#include "ap_provider.h"
#include "apr_pools.h"

/* If this flag is set, the provider guarantees persistent storage of data;
 * if unset, data may be ejected as the provider deems necessary.
#define AP_DICT_FLAG_PERSIST (0x0001)

/* If this flag is set, the provider sets no fixed limit on the number of
 * key/value data pairs it can store.
#define AP_DICT_FLAG_NO_LIMIT (0x0002)

/* This this flag is set, the provider guarantees that stored data will
 * remain consistent if multiple processes or threads make concurrent calls
 * to the provider's functions. 
#define AP_DICT_FLAG_ATOMIC (0x0004) 

/* If passed in a klen argument, the provider will used strlen(key)
 * to determine the key length.
#define AP_DICT_KEY_STRING (-1)

typedef struct ap_dict_provider_t {
    /* Canonical provider name: */ 
    const char *name;

    /* Bitmask of AP_DICT_FLAG_* flags: */
    unsigned int flags;
    /* Create a dictionary based on the configuration parameters in
     * params.  Returns NULL on success, or an error string on failure.
     * Pool tmp should be used for any temporary allocations, pool p
     * should be used for any allocations that should last as long as the
     * lifetime of the return context.
     * The context pointer returned in *instance will be passed as the
     * first argument to subsequent invocations.
    const char *(*create)(void **instance, const char *params,
                          apr_pool_t *tmp, apr_pool_t *p);

    /* Initialize the dictionary.  Return APR error code.   */
    apr_status_t (*init)(void *instance, /* hints, namespace */
                         server_rec *s, apr_pool_t *pool);

    /* Destroy a given dictionary context. */
    void (*destroy)(void *instance, server_rec *s);

    /* Store an object in the dictionary.  If expiry is zero, the
     * provider will attempt to retain the data as long as possible.
    apr_status_t (*store)(void *instance, server_rec *s,
                          const char *key, apr_size_t klen,
                          apr_interval_time_t expiry,
                          char *val, apr_size_t vlen);

    /* Retrieve stored data with key of length klen, returning APR_SUCCESS
     * on success or an APR error code otherwise.  Upon success,
     * the data will be written to *val, up to a maximum number of bytes
     * specified on entry by *vlen, and *vlen will be updated to the
     * length of the data written.
    apr_status_t (*fetch)(void *instance, server_rec *s,
                          const char *key, apr_size_t klen,
                          char *val, apr_size_t *vlen,
                          apr_pool_t *pool);

    /* Remove an object from the dictionary. */
    void (*delete)(void *instance, server_rec *s,
                   const char *key, apr_size_t klen,
                   apr_pool_t *pool);

    /* Dump dictionary status for mod_status output. */
    void (*status)(void *instance, request_rec *r, int flags);
} ap_dict_provider_t;

/* Dictionary providers are registered using the ap_provider_* interface,
 * with the following group and version:

#endif /* AP_DICT_H */
/** @} */

View raw message