GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CACHE::AGAINSTFILE (3)

.ds Aq ’

NAME

Cache::AgainstFile - Cache data structures parsed from files, watching for updates to the file

CONTENTS

SYNOPSIS



        use Cache::AgainstFile;
        my $cache = new Cache::AgainstFile(\&loader, \%options);
        $cache->get($filename);
        $cache->purge();

        sub loader {
                my $filename = shift;
                my $data_structure = do_really_expensive_parsing($filename);
                return $data_structure;
        }



DESCRIPTION

A module that caches a data structure against a filename, statting the file to determine whether it has changed and needs to be re-parsed. You supply a routine to generate the data structure given the filename.

This module is recommended for files which change infrequently but are read often, especially if they are expensive to parse. Example uses include caching precompiled templates, pre-parsed XML or data files on webservers.

This approach has the advantage over lazy caching (where cache items are not validated for a period of time) that multiple processes (e.g. modperl daemons) holding a cache will all update at the same time so you will not get inconsistent results if you request data from different processes.

The module itself is simply a factory for various backend modules (each exposing the same API). The distribution includes backends for in-memory caching or file caching using Storable, plus an adaptor to use any modules offering the Cache or Cache::Cache interfaces as the cache implementation.

Data structures are automatically serialised/deserialised by the backend modules if they are being persisted somewhere other than in memory (e.g. on the filesystem).

API

The interface is designed to match that of Cache and Cache::Cache:
new(\&loader, \%options)


 &loader is a subroutine which given a filename, returns a scalar to cache 
 %options can contain:



Method Cache implementation (required). Valid values are: Memory|Storable|CacheModule|Null or a package name supporting the Cache::AgainstFile interface.
NoStat Don’t stat files to validate the cache - items are served from the cache without checking if the source files have changed, until they are purged.

Valid values are 0|1 (default=0, i.e. files are statted)

Also see the options for the backend associated with Method.

get($filename, @options) Fetches the scalar associated with $filename. You may optionally supply a list of other arguments which get passed to the loader routine
purge() Purges stale items from the cache according to the options supplied to the constructor. Items which are not stale remain in the cache.
clear() Dumps the entire cache (including items which are not stale)
count() Returns the number of items in the cache. Note that this method (present in the Cache API) is an addition to the Cache::Cache API.
size() Returns the total size of the cache in bytes (may return undef if this is not implemented in the backend)

WARNINGS

If you are caching blessed objects to disk either using the Storable backend or a filesystem caching module through Cache::AgainstFile::CacheModule, make sure the code for the class has been compiled into the process you are loading cache items into. Normally this isn’t a problem if you explicitly use the class, but if you are loading classes at runtime, make sure that the appropriate class is loaded before any objects of that class are fetched from cache.

Different backends may adopt slightly different rules regarding checking the source file’s mtime. Any approach could be vulnerable to odd conditions which result in the source file at any given time having more than one possible set of contents (e.g. multiple nonatomic writes in a second) or the use of utilities (such as tar) which change contents, then set mtime to some time in the past. The default behaviour should be pretty resilient but you may want to pay attention to Locking options if using the Storable backend.

SEE ALSO

Cache::AgainstFile::Memory In-memory cache.
Cache::AgainstFile::Storable On-disk cache using storable to serialize data structures.
Cache::AgainstFile::CacheModule Modules with the following interfaces can be used as the caching implementation:
Cache::Cache a set of modules for lazy caching
Cache a rewrite of Cache::Cache with extra features such as validation callbacks

VERSION

$Revision: 1.16 $ on $Date: 2006/05/09 09:04:29 $ by $Author: mattheww $

AUTHOR

John Alden & Piers Kent <cpan _at_ bbc _dot_ co _dot_ uk>

COPYRIGHT

(c) BBC 2005. This program is free software; you can redistribute it and/or modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CACHE::AGAINSTFILE (3) 2006-05-09

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.