NAME¶
Cache::Mmap - Shared data cache using memory mapped files
SYNOPSIS¶
use Cache::Mmap;
$cache=Cache::Mmap->new($filename,\%options);
$val1=$cache->read($key1);
$cache->write($key2,$val2);
$cache->delete($key3);
DESCRIPTION¶
This module implements a shared data cache, using memory mapped files. If
routines are provided which interact with the underlying data, access to the
cache is completely transparent, and the module handles all the details of
refreshing cache contents, and updating underlying data, if necessary.
Cache entries are assigned to "buckets" within the cache file,
depending on the key. Within each bucket, entries are stored approximately in
order of last access, so that frequently accessed entries will move to the
head of the bucket, thus decreasing access time. Concurrent accesses to the
same bucket are prevented by file locking of the relevant section of the cache
file.
CLASS METHODS¶
- new($filename,\%options)
- Creates a new cache object. If the file named by $filename
does not already exist, it will be created. If the cache object cannot be
created for any reason, an exception will be thrown. Various options may
be set in %options, which affect the behaviour of the cache (defaults in
parentheses):
- permissions (0600)
- Sets the file permissions for the cache file if it doesn't
already exist.
- buckets (13)
- Sets the number of buckets inside the cache file. A larger
number of buckets will give better performance for a cache with many
accesses, as there will be less chance of concurrent access to the same
bucket.
- bucketsize (1024)
- Sets the size of each bucket, in bytes. A larger bucket
size will be needed to store large cache entries. If the bucketsize is not
large enough to hold a particular entry, it will still be passed between
the underlying data and the application in its entirety, but will not be
stored in the cache.
- pagesize (1024)
- Sets the alignment of buckets within the file. The file
header will be extended to this size, and bucket sizes will be rounded up
to the nearest multiple. Choosing a pagesize equal to the virtual memory
page size of the host system should improve performance.
- strings (0)
- If true, cache entries are treated as strings, rather than
references. This will help performance for string-only caches, as no time
will be taken to serialize cache entries.
- expiry (0)
- If non-zero, sets the length of time, in seconds, which
cache entries are considered valid. A new entry will be fetched from the
underlying data if an expired cache entry would otherwise have been
returned.
- context (undef)
- This value is passed to the read/write/delete routines
below, to provide context. This will typically be a database handle, used
to fetch data from.
- read (undef)
- Provides a code reference to a routine which will fetch
entries from the underlying data. Called as
"$read->($key,$context)", this routine should return a list
"($found,$value)", where $found is true if the entry could be
found in the underlying data, and $value is the value to cache.
If the routine only returns a single scalar, that will be taken as the
value, and $found will be set to true if the value is defined.
If this routine is not provided, only values already in the cache will ever
be returned.
There are currently two special values of $found which cause slightly
different behaviour. These are constants which may be imported in the
"use" statement.
- "Cache::Mmap::CMM_keep_expired"
- Use the previously cached value, even if it has expired.
This is useful if the underlying data source has become unavailable for
some reason. Note that even though the value returned will be ignored in
this case, it must be returned to avoid $found being interpreted as a
single scalar:
return (Cache::Mmap::CMM_keep_expired, undef);
- "Cache::Mmap::CMM_keep_expired_refresh"
- This causes the same behaviour as
"CMM_keep_expired", but the cache entry's expiry time will be
reset as if a value had been successfully read from the underlying
data.
- cachenegative (0)
- If true, even unsuccessful fetches from the underlying data
are cached. This can be useful to only search the underlying data once for
each required key.
- write (undef)
- Provides a code reference to a routine which will write
cache entries into the underlying data. This routine will be called by
write(), to synchronise the underlying data with the cache. Called
as "$write->($key,$val,$context)". If the routine is not
provided, the underlying data will not be synchronised after cache
writes.
- writethrough (1)
- If true, the "write" routine above will be called
as soon as write() is called. This provides immediate
synchronisation of underlying data and cache contents.
If false, the "write" routine will be called for each cache entry
which no longer fits in its bucket after a cache read or write. This
provides a write-as-necessary behaviour, which may be more efficient than
the writethrough behaviour. However, only data fetched through the cache
will reflect these changes.
- delete (undef)
- Provides a code reference to a routine which will delete
items from the underlying data. This routine will be called by
delete(), to synchronise the underlying data with the cache. Called
as "$delete->($key,$cval,$context)", where $cval is the value
currently stored in the cache. If this routine is not provided, entries
deleted from the cache have no effect on the underlying data.
An alternative to supplying a "write" routine, is to call
delete() after updating the underlying data. Note however, that in the
case of databases, this should be done after committing the update, so that a
concurrent process doesn't reload the cache between being the entry being
deleted, and the database updates being committed.
METHODS¶
CACHE DATA METHODS¶
These are the everyday methods used to access the data stored by the cache.
- read($key)
- Reads an entry from the cache, or from the underlying data
if not cached. Returns the value in scalar context, and
"($found,$value)" in list context, where $found is true if the
item was found in either the cache or the underlying data.
- write($key,$val)
- Writes an entry into the cache, and depending on the
configuration, into the underlying data.
- delete($key)
- Deletes an entry from the cache, and depending on
"new()" options, from the underlying data. Returns the value in
scalar context, and "($found,$value)" in list context, where
$found is true if the item was found in the cache.
- entries()
- entries(0)
- Returns a list of the keys of entries held in the cache.
Note that this list may be immediately out of date, due to the shared
nature of the cache. Entries may be added or removed by other processes
between this list being generated and when it is used.
- entries(1)
- Returns a list of hashrefs representing entries held in the
cache. The following keys are present in each hashref:
key The key used to identify the entry
time The time the entry was stored (seconds since the epoch)
dirty Whether the entry needs writing to the underlying data
The same caveat applies to the currency of this information as above.
- entries(2)
- As entries(1), with the addition of a "value"
element in each hashref, holding the value stored in the cache entry.
- quick_clear()
- Forcefully delete the cache, with prejudice. Unwritten
dirty elements are not written back to the underlying data source;
they are simply thrown away.
CONFIGURATION METHODS¶
These methods are used to examine/update the configuration of a cache. Most of
these methods are read-only, and the value returned may be different to that
passed to the constructor, since the cache may have been created by an earlier
process which specified different parameters.
- buckets()
- Returns the number of buckets in the cache file.
- bucketsize()
- Returns the size of buckets (in bytes) in the cache
file.
- cachenegative()
- Returns true if items not found in the underlying data are
cached anyway.
- context()
- Returns the context data for reads and writes to the
underlying data.
- context($context)
- Provides new context data for reads and writes to the
underlying data.
- expiry()
- Returns the time in seconds cache entries are considered
valid for, or zero for indefinite validity.
- pagesize()
- Returns the page size (in bytes) of the cache file.
- strings()
- Returns true if the cache stores strings rather than
references.
- writethrough()
- Returns true if items written to the cache are immediately
written to the underlying data.
AUTHOR¶
Copyright (C) Institute of Physics Publishing 2002-2008
Peter Haworth <pmh@edison.ioppublishing.com>
You may distribute under the terms of the GPL or the Artistic License, as
distributed with Perl.
