.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Cache 3pm"
.TH Cache 3pm "2015-07-25" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Cache \- the Cache interface
.SH "DESCRIPTION"
.IX Header "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.
.PP
The Cache interface is implemented by derived classes that store cached data
in different manners (such as files on a filesystem, or in memory).
.SH "USAGE"
.IX Header "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.
.PP
Using a cache is simple.  Here is some very simple sample code for
instantiating and using a file system based cache.
.PP
.Vb 1
\&  use Cache::File;
\&
\&  my $cache = Cache::File\->new( cache_root => \*(Aq/tmp/cacheroot\*(Aq );
\&  my $customer = $cache\->get( $name );
\&
\&  unless ($customer) {
\&      $customer = get_customer_from_db( $name );
\&      $cache\->set( $name, $customer, \*(Aq10 minutes\*(Aq );
\&  }
\&
\&  return $customer;
.Ve
.PP
Of course, far more powerful methods are available for accessing cached data.
Also see the \s-1TIE INTERFACE\s0 below.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "my $cache_entry = $c\->entry( $key )" 4
.el .IP "my \f(CW$cache_entry\fR = \f(CW$c\fR\->entry( \f(CW$key\fR )" 4
.IX Item "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.
.ie n .IP "$c\->\fIpurge()\fR" 4
.el .IP "\f(CW$c\fR\->\fIpurge()\fR" 4
.IX Item "$c->purge()"
Remove all expired data from the cache.
.ie n .IP "$c\->\fIclear()\fR" 4
.el .IP "\f(CW$c\fR\->\fIclear()\fR" 4
.IX Item "$c->clear()"
Remove all entries from the cache \- regardless of their expiry time.
.ie n .IP "my $num = $c\->\fIcount()\fR" 4
.el .IP "my \f(CW$num\fR = \f(CW$c\fR\->\fIcount()\fR" 4
.IX Item "my $num = $c->count()"
Returns the number of entries in the cache.
.ie n .IP "my $size = $c\->\fIsize()\fR" 4
.el .IP "my \f(CW$size\fR = \f(CW$c\fR\->\fIsize()\fR" 4
.IX Item "my $size = $c->size()"
Returns the size (in bytes) of the cache.
.SH "PROPERTIES"
.IX Header "PROPERTIES"
When a cache is constructed these properties can be supplied as options to the
\&\fInew()\fR method.
.IP "default_expires" 4
.IX Item "default_expires"
The current default expiry time for new entries into the cache.  This property
can also be reset at any time.
.Sp
.Vb 2
\& my $time = $c\->default_expires();
\& $c\->set_default_expires( $expiry );
.Ve
.IP "removal_strategy" 4
.IX Item "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.
.Sp
When setting the removal strategy in \fInew()\fR, 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 \fInew()\fR method of the named package).
.Sp
The strategies 'Cache::RemovalStrategy::LRU' and
\&'Cache::RemovalStrategy::FIFO' are available by default.
.Sp
.Vb 1
\& my $strategy = $c\->removal_strategy();
.Ve
.IP "size_limit" 4
.IX Item "size_limit"
The size limit for the cache.
.Sp
.Vb 1
\& my $limit = $c\->size_limit();
.Ve
.IP "load_callback" 4
.IX Item "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.
.Sp
.Vb 2
\& my $limit = $c\->load_callback();
\& $c\->set_load_callback($callback_func);
.Ve
.IP "validate_callback" 4
.IX Item "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.
.Sp
.Vb 2
\& my $limit = $c\->validate_callback();
\& $c\->set_validate_callback($callback_func);
.Ve
.SH "SHORTCUT METHODS"
.IX Header "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)\->\fImethod_name()\fR'.  For documentation, please refer to
Cache::Entry.
.ie n .IP "my $bool = $c\->exists( $key )" 4
.el .IP "my \f(CW$bool\fR = \f(CW$c\fR\->exists( \f(CW$key\fR )" 4
.IX Item "my $bool = $c->exists( $key )"
.PD 0
.ie n .IP "$c\->set( $key, $data, [ $expiry ] )" 4
.el .IP "\f(CW$c\fR\->set( \f(CW$key\fR, \f(CW$data\fR, [ \f(CW$expiry\fR ] )" 4
.IX Item "$c->set( $key, $data, [ $expiry ] )"
.ie n .IP "my $data = $c\->get( $key )" 4
.el .IP "my \f(CW$data\fR = \f(CW$c\fR\->get( \f(CW$key\fR )" 4
.IX Item "my $data = $c->get( $key )"
.ie n .IP "my $data = $c\->size( $key )" 4
.el .IP "my \f(CW$data\fR = \f(CW$c\fR\->size( \f(CW$key\fR )" 4
.IX Item "my $data = $c->size( $key )"
.ie n .IP "$c\->remove( $key )" 4
.el .IP "\f(CW$c\fR\->remove( \f(CW$key\fR )" 4
.IX Item "$c->remove( $key )"
.ie n .IP "$c\->expiry( $key )" 4
.el .IP "\f(CW$c\fR\->expiry( \f(CW$key\fR )" 4
.IX Item "$c->expiry( $key )"
.ie n .IP "$c\->set_expiry( $key, $time )" 4
.el .IP "\f(CW$c\fR\->set_expiry( \f(CW$key\fR, \f(CW$time\fR )" 4
.IX Item "$c->set_expiry( $key, $time )"
.ie n .IP "$c\->handle( $key, [$mode, [$expiry] ] )" 4
.el .IP "\f(CW$c\fR\->handle( \f(CW$key\fR, [$mode, [$expiry] ] )" 4
.IX Item "$c->handle( $key, [$mode, [$expiry] ] )"
.ie n .IP "$c\->validity( $key )" 4
.el .IP "\f(CW$c\fR\->validity( \f(CW$key\fR )" 4
.IX Item "$c->validity( $key )"
.ie n .IP "$c\->set_validity( $key, $data )" 4
.el .IP "\f(CW$c\fR\->set_validity( \f(CW$key\fR, \f(CW$data\fR )" 4
.IX Item "$c->set_validity( $key, $data )"
.ie n .IP "$c\->freeze( $key, $data, [ $expiry ] )" 4
.el .IP "\f(CW$c\fR\->freeze( \f(CW$key\fR, \f(CW$data\fR, [ \f(CW$expiry\fR ] )" 4
.IX Item "$c->freeze( $key, $data, [ $expiry ] )"
.ie n .IP "$c\->thaw( $key )" 4
.el .IP "\f(CW$c\fR\->thaw( \f(CW$key\fR )" 4
.IX Item "$c->thaw( $key )"
.PD
.SH "TIE INTERFACE"
.IX Header "TIE INTERFACE"
.Vb 1
\&  tie %hash, \*(AqCache::File\*(Aq, { cache_root => $tempdir };
\&
\&  $hash{\*(Aqkey\*(Aq} = \*(Aqsome data\*(Aq;
\&  $data = $hash{\*(Aqkey\*(Aq};
.Ve
.PP
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.
.PP
The tie interface is especially useful with the load_callback to automatically
populate the hash.
.SH "REMOVAL STRATEGY METHODS"
.IX Header "REMOVAL STRATEGY METHODS"
These methods are only for use internally (by concrete Cache implementations).
.PP
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 \s-1FIFO\s0 and \s-1LRU\s0 removal
strategies.  All derived Cache implementations should support these methods
and may also introduce additional methods (and additional removal strategies
to match).
.ie n .IP "my $size = $c\->\fIremove_oldest()\fR" 4
.el .IP "my \f(CW$size\fR = \f(CW$c\fR\->\fIremove_oldest()\fR" 4
.IX Item "my $size = $c->remove_oldest()"
Removes the oldest entry in the cache and returns its size.
.ie n .IP "my $size = $c\->\fIremove_stalest()\fR" 4
.el .IP "my \f(CW$size\fR = \f(CW$c\fR\->\fIremove_stalest()\fR" 4
.IX Item "my $size = $c->remove_stalest()"
Removes the 'stalest' (least used) object in the cache and returns its
size.
.ie n .IP "$c\->check_size( $size )" 4
.el .IP "\f(CW$c\fR\->check_size( \f(CW$size\fR )" 4
.IX Item "$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.
.SH "UTILITY METHODS"
.IX Header "UTILITY METHODS"
These methods are only for use internally (by concrete Cache implementations).
.ie n .IP "my $time = Cache::Canonicalize_Expiration_Time($timespec)" 4
.el .IP "my \f(CW$time\fR = Cache::Canonicalize_Expiration_Time($timespec)" 4
.IX Item "my $time = Cache::Canonicalize_Expiration_Time($timespec)"
Converts a timespec as described for \fICache::Entry::set_expiry()\fR into a unix
time.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Cache::Entry, Cache::File, Cache::RemovalStrategy
.SH "DIFFERENCES FROM CACHE::CACHE"
.IX Header "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.
.PP
The semantics of use are very similar to Cache::Cache, with the following
exceptions:
.IP "The get/set methods \s-1DO NOT\s0 serialize complex data types.  Use freeze/thaw instead (but read the notes in Cache::Entry)." 4
.IX Item "The get/set methods DO NOT serialize complex data types. Use freeze/thaw instead (but read the notes in Cache::Entry)."
.PD 0
.IP "The get_object / set_object methods are not available, but have been superseded by the more flexible entry method and Cache::Entry class." 4
.IX Item "The get_object / set_object methods are not available, but have been superseded by the more flexible entry method and Cache::Entry class."
.IP "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." 4
.IX Item "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."
.IP "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." 4
.IX Item "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."
.IP "Cache::SharedMemory is not yet available." 4
.IX Item "Cache::SharedMemory is not yet available."
.IP "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." 4
.IX Item "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."
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\& Chris Leishman <chris@leishman.org>
\& Based on work by DeWitt Clinton <dewitt@unto.net>
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 1
\& Copyright (C) 2003\-2006 Chris Leishman.  All Rights Reserved.
.Ve
.PP
This module is distributed on an \*(L"\s-1AS IS\*(R"\s0 basis, \s-1WITHOUT WARRANTY OF ANY KIND,\s0
either expressed or implied. This program is free software; you can
redistribute or modify it under the same terms as Perl itself.
.PP
\&\f(CW$Id:\fR Cache.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $