2026-05-21 22:08 @216.73.216.105 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
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 $
Generated by phpMan Author: Che Dong On Apache Under GNU General Public License - MarkDown Format
2026-05-21 22:08 @216.73.216.105 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)