DSSX_Cache
DSSX_Cache
dssx
1998 12-06
CLASS
DSSX_Cache - A DSS extended construct analogous to a cache
SYNOPSIS
This class provides a cache-like construct built using DSS.
DSSX_Cache provides a fixed number of entries that is set during
cache construction.
An entry is basicly a DSS_Chunk with a cache specific name. Therefore,
entries themselves are not fixed in size.
The basic idea of DSSX_Cache is that the Atomic() member function checks for
an entry matching a key and returns the corresponding data. If Atomic() does
not find an entry matching the key, it populates an entry for that key with
the user provided function.
PARENTS
CONSTRUCTOR
DSSX_Cache(DSSX_Connection *connection, char *spacename, char *cachename, unsigned long num_entries, DSS_ChunkConfig *config)
Construct a DSSX_Cache using connection in space spacename
named cachename. On the first construction of a particular
DSSX_Cache the number of entries is fixed at num_entries.
However, for subsequent constructions on the same cache (same spacename and
cachename) the num_entries argument is ignored.
The config
argument is only used to set memory type and is only used on the first
construction. See the manpage for DSS_ChunkConfig for details.
MEMBER FUNCTIONS
char *Check(char *key, unsigned long keylen, unsigned long *size)
Check for an entry for the key specified by key and keylen.
If one is found return a pointer to the data and return the size in
size. Otherwise return NULL.
The buffer returned by this function is allocated by this function and it is
the caller's responsibility to free it when done.
long Check(GPL_CharPtr key, GPL_Message *value)
A GPL_Message variant of Check().
Returns TRUE if an entry is found, otherwise FALSE is returned.
void Fill(char *key, unsigned long keylen, char *buffer, unsigned long size)
Fill the entry for the key specified by key and keylen
with the data chunk specified by buffer and size.
void Fill(GPL_CharPtr key, GPL_Message *value)
A GPL_Message variant of Fill().
char *Hold(char *key, unsigned long keylen, unsigned long *size)
Check for an entry for the key specified by key and keylen.
If one is found return a pointer to the data and return the size in
size. Otherwise return NULL.
The buffer returned by this function is allocated by this function and it is
the caller's responsibility to free it when done.
This function will prevent access to the entry until Release() is called.
long Hold(GPL_CharPtr key, GPL_Message *value)
A GPL_Message variant of Hold().
Returns TRUE if an entry is found, otherwise FALSE is returned.
void Release(char *key, unsigned long keylen, char *buffer, unsigned long size)
Fill the entry for the key specified by key and keylen
with the data chunk specified by buffer and size.
This function opens access to the entry that had been prevented by Hold(). This
function should not be called without a preceding call of Hold().
void Release(GPL_CharPtr key, GPL_Message *value)
A GPL_Message variant of Release().
char *Atomic(char *key, unsigned long keylen, char *(*miss_function)(char *miss_key, unsigned long miss_keylen, void *, unsigned long *miss_size), void *miss_arg, unsigned long *size)
This is the primary access function for data in the cache.
This function returns the data corresponding to the provided key and
keylen. The size of the chunk of data is return in the argument
size. If there is no entry corresponding to the provided
key the function miss_function is called with miss_key set to
key and arg set to miss_arg. The function miss_function
should return data to populate the entry with and return the size of the chunk
in miss_size.
Note that this function is atomic whereas using Check() and Fill() to do the
same job is not atomic.
The returned buffer is allocated by this function and it is the caller's
responsibility to free it when done. Also, the buffer returned by
miss_function() should be allocated by miss_function() since Atomic() may
attempt to free that particular buffer.
long Atomic(GPL_CharPtr key, void (*miss_function)(GPL_CharPtr miss_key, void *, GPL_Message *miss_message), void *miss_arg, GPL_Message *value)
A variant of Atomic() that returns TRUE on success and FALSE on failure.
void Clear(char *key, unsigned long keylen)
Clear the entry corresponding to the specified key and keylen.
void Clear(GPL_CharPtr key)
A variant of Clear().
void Invalidate()
Invalidate all underlying DSS chunks that implement the DSSX_Cache. After
this call any other member function (except the destructor) have undefined
behavior.
unsigned long Heuristic(GPL_CharPtr key)
A variant of Heuristic().
This version calls the virtual version below and is not itself virtual.
virtual unsigned long Heuristic(char *key, unsigned long keylen)
This is the function used to convert the key
to an unsigned long to match a specific cache entry with the key. The default
method is to sum the ascii values of the characters making up the key.
This may be replaced by a more appropriate method if necessary.