Hi --
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.
I have to retract "mod_dict", since "dictionary" usually implies an
ordered set of keys, and that's not the case with these providers. But,
what about "mod_shmap" for "shared map", since I think what is common to
all these providers is essentially a shared associative array, with a
mapping from keys to values. Thoughts?
Chris.
=========================================
/**
* @file ap_shmap.h
* @brief Shared associative array provider interface.
*
* @defgroup AP_SHMAP ap_shmap
* @ingroup APACHE_MODS
* @{
*/
#ifndef AP_SHMAP_H
#define AP_SHMAP_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_SHMAP_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_SHMAP_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_SHMAP_FLAG_ATOMIC (0x0004)
/* If passed in a klen argument, the provider will used strlen(key)
* to determine the key length.
*/
#define AP_SHMAP_KEY_STRING (-1)
typedef struct ap_shmap_provider_t {
/* Canonical provider name: */
const char *name;
/* Bitmask of AP_SHMAP_FLAG_* flags: */
unsigned int flags;
/* Create a shared map 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 shared map. Return APR error code. */
apr_status_t (*init)(void *instance, /* hints, namespace */
server_rec *s, apr_pool_t *pool);
/* Destroy a given shared map context. */
void (*destroy)(void *instance, server_rec *s);
/* Store an object in the shared map. 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 shared map. */
void (*delete)(void *instance, server_rec *s,
const char *key, apr_size_t klen,
apr_pool_t *pool);
/* Dump shared map status for mod_status output. */
void (*status)(void *instance, request_rec *r, int flags);
} ap_shmap_provider_t;
/* Dictionary providers are registered using the ap_provider_* interface,
* with the following group and version:
*/
#define AP_SHMAP_PROVIDER_GROUP "shmap"
#define AP_SHMAP_PROVIDER_VERSION "0"
#endif /* AP_SHMAP_H */
/** @} */
