man > CACHE

Cache(3pm)                       User Contributed Perl Documentation                      Cache(3pm)

NAME
       Cache - the Cache interface

DESCRIPTION
       The Cache modules are designed to assist a developer in persisting data for a specified
       period of time.  Often these modules are used in web applications to store data locally to
       save repeated and redundant expensive calls to remote machines or databases.

       The Cache interface is implemented by derived classes that store cached data in different
       manners (such as files on a filesystem, or in memory).

USAGE
       To use the Cache system, a cache implementation must be chosen to suit your needs.  The most
       common is Cache::File, which is suitable for sharing data between multiple invocations and
       even between concurrent processes.

       Using a cache is simple.  Here is some very simple sample code for instantiating and using a
       file system based cache.

         use Cache::File;

         my $cache = Cache::File->new( cache_root => '/tmp/cacheroot' );
         my $customer = $cache->get( $name );

         unless ($customer) {
             $customer = get_customer_from_db( $name );
             $cache->set( $name, $customer, '10 minutes' );
         }

         return $customer;

       Of course, far more powerful methods are available for accessing cached data.  Also see the
       TIE INTERFACE below.

METHODS
       my $cache_entry = $c->entry( $key )
           Return  a  'Cache::Entry'  object  for  the  given  key.  This object can then be used to
           manipulate the cache entry in various ways.  The key can be any scalar string  that  will
           uniquely identify an entry in the cache.

       $c->purge()
           Remove all expired data from the cache.

       $c->clear()
           Remove all entries from the cache - regardless of their expiry time.

       my $num = $c->count()
           Returns the number of entries in the cache.

       my $size = $c->size()
           Returns the size (in bytes) of the cache.

PROPERTIES
       When a cache is constructed these properties can be supplied as options to the new() method.

       default_expires
           The  current  default expiry time for new entries into the cache.  This property can also
           be reset at any time.

            my $time = $c->default_expires();
            $c->set_default_expires( $expiry );

       removal_strategy
           The removal strategy object for the cache.  This is used to remove object from the  cache
           in order to maintain the cache size limit.

           When  setting  the removal strategy in new(), the name of a strategy package or a blessed
           strategy object  reference  should  be  provided   (in  the  former  case  an  object  is
           constructed by calling the new() method of the named package).

           The   strategies  'Cache::RemovalStrategy::LRU'  and  'Cache::RemovalStrategy::FIFO'  are
           available by default.

            my $strategy = $c->removal_strategy();

       size_limit
           The size limit for the cache.

            my $limit = $c->size_limit();

       load_callback
           The load callback for the cache.  This may be set to a  function  that  will  get  called
           anytime a 'get' is issued for data that does not exist in the cache.

            my $limit = $c->load_callback();
            $c->set_load_callback($callback_func);

       validate_callback
           The  validate callback for the cache.  This may be set to a function that will get called
           anytime a 'get' is issued for data that does not exist in the cache.

            my $limit = $c->validate_callback();
            $c->set_validate_callback($callback_func);

SHORTCUT METHODS
       These methods all have counterparts in the Cache::Entry package, but  are  provided  here  as
       shortcuts.   They all default to just wrappers that do '$c->entry($key)->method_name()'.  For
       documentation, please refer to Cache::Entry.

       my $bool = $c->exists( $key )
       $c->set( $key, $data, [ $expiry ] )
       my $data = $c->get( $key )
       my $data = $c->size( $key )
       $c->remove( $key )
       $c->expiry( $key )
       $c->set_expiry( $key, $time )
       $c->handle( $key, [$mode, [$expiry] ] )
       $c->validity( $key )
       $c->set_validity( $key, $data )
       $c->freeze( $key, $data, [ $expiry ] )
       $c->thaw( $key )

TIE INTERFACE
         tie %hash, 'Cache::File', { cache_root => $tempdir };

         $hash{'key'} = 'some data';
         $data = $hash{'key'};

       The Cache classes can be used via the tie interface, as shown in the synopsis.   This  allows
       the  cache  to  be  accessed via a hash.  All the standard methods for accessing the hash are
       supported , with the exception of the 'keys' or 'each' call.

       The tie interface is especially useful with the load_callback to automatically  populate  the
       hash.

REMOVAL STRATEGY METHODS
       These methods are only for use internally (by concrete Cache implementations).

       These  methods  define  the interface by which the removal strategy object can manipulate the
       cache (the Cache is the 'context' of the strategy).  By default, methods need to be  provided
       to  remove the oldest or stalest objects in the cache - thus allowing support for the default
       FIFO and LRU removal strategies.  All derived  Cache  implementations  should  support  these
       methods  and  may  also  introduce  additional  methods (and additional removal strategies to
       match).

       my $size = $c->remove_oldest()
           Removes the oldest entry in the cache and returns its size.

       my $size = $c->remove_stalest()
           Removes the 'stalest' (least used) object in the cache and returns its size.

       $c->check_size( $size )
           This method isn't actually part of the strategy interface, nor does it need to be defined
           by Cache implementations.  Instead it should be called by  implementations  whenever  the
           size  of  the cache increases.  It will take care of checking the size limit and invoking
           the removal strategy if required.  The size argument should be the new size of the cache.

UTILITY METHODS
       These methods are only for use internally (by concrete Cache implementations).

       my $time = Cache::Canonicalize_Expiration_Time($timespec)
           Converts a timespec as described for Cache::Entry::set_expiry() into a unix time.

SEE ALSO
       Cache::Entry, Cache::File, Cache::RemovalStrategy

DIFFERENCES FROM CACHE::CACHE
       The Cache modules are a total redesign and reimplementation  of  Cache::Cache  and  thus  not
       directly  compatible.   It  would  be, however, quite possible to write a wrapper module that
       provides an identical interface to Cache::Cache.

       The semantics of use are very similar to Cache::Cache, with the following exceptions:

       The get/set methods DO NOT serialize complex data types.  Use freeze/thaw instead (but read
       the notes in Cache::Entry).
       The get_object / set_object methods are not available, but have been superseded by the more
       flexible entry method and Cache::Entry class.
       There is no concept of 'namespace' in the basic cache interface, although implementations
       (eg. Cache::Memory) may choose to provide them.  For instance, File::Cache does not provide
       this - but different namespaces can be created by varying cache_root.
       In the current Cache implementations purging is done automatically - there is no need to
       explicitly enable auto purge on get/set.  The purging algorithm is no longer implemented in
       the base Cache class, but is left up to the implementations and may thus be implemented in
       the most efficient way for the storage medium.
       Cache::SharedMemory is not yet available.
       Cache::File no longer supports separate masks for entries and directories.  It is not a very
       secure configuration and presents numerous issues for cache consistency and is hence
       deprecated.  There is still some work to be done to ensure cache consistency between accesses
       by different users.

AUTHOR
        Chris Leishman <chris AT leishman.org>
        Based on work by DeWitt Clinton <dewitt AT unto.net>

COPYRIGHT
        Copyright (C) 2003-2006 Chris Leishman.  All Rights Reserved.

       This module is distributed on an  "AS  IS"  basis,  WITHOUT  WARRANTY  OF  ANY  KIND,  either
       expressed  or implied. This program is free software; you can redistribute or modify it under
       the same terms as Perl itself.

       $Id: Cache.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $

perl v5.34.0                                 2022-06-09                                   Cache(3pm)