Cache::Mmap - Shared data cache using memory mapped files
use Cache::Mmap;
$cache=Cache::Mmap->new($filename,\%options);
$val1=$cache->read($key1);
$cache->write($key2,$val2);
$cache->delete($key3);
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.
- 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.
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.
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.
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.