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.