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 apporximately 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 relevent section of the cache file.

METHODS

Cache::Mmap->new($filename,\%options)

Creates a new cache object. If the file named by $filename does not already exist, it will be created. 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, or undef if not found. If this routine is not provided, only values already in the cache will ever be returned.

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 after $cache->write() is called, 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 $cache->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 after $cache-delete()> is called, to synchronise the underlying data with the cache. Called as $cache->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 $cache->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.

$cache->buckets()

Returns the number of buckets in the cache file. Note that this may be different to the number passed to new(), since an existing cache file may have been created with different options.

$cache->bucketsize()

Returns the size of buckets in the cache file. May be different to new() parameter.

$cache->pagesize()

Returns the page size of the cache file. May be different to new() parameter.

$cache->strings()

Returns true if the cache stores strings rather than references. May be different to new() parameter.

$cache->expiry()

Returns the time in seconds cache entries are considered valid for, or zero for indefinite validity. May be different to new() parameter.

$cache->writethrough()

Returns true if items written to the cache are immediately written to the underlying data. May be different to new() parameter.

$cache->cachenegative()

Returns true if items not found in the underlying data are cached anyway. May be different to new() parameter.

$cache->context()

Returns the context data for reads and writes to the underlying data.

$cache->context($context)

Provides new context data for reads and writes to the underlying data.

$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.

$cache->write($key,$val)

Writes an entry into the cache, and depending on new() options, into the underlying data.

$cache->delete($key)

Deletes an entry from the cache, and depending on new() options, from the underlying data.

$cache->entries()

$cache->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.

$cache->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.

$cache->entries(2)

As $cache->entries(1), with the addition of a value element in each hashref, holding the value stored in the cache entry.

AUTHOR

Peter Haworth <pmh@edison.ioppublishing.com>