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.
Chris.
====================================
/**
* @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:
*/
#define AP_DICT_PROVIDER_GROUP "dict"
#define AP_DICT_PROVIDER_VERSION "0"
#endif /* AP_DICT_H */
/** @} */
