.\" 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::Cache 3pm"
.TH Cache::Cache 3pm "2015-01-22" "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::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.  People have also
been known to use Cache::Cache for its straightforward interface in
sharing data between runs of an application or invocations of a
CGI-style script or simply as an easy to use abstraction of the
filesystem or shared memory.
.PP
The Cache::Cache interface is implemented by classes that support the
get, set, remove, size, purge, and clear instance methods and their
corresponding static methods for persisting data across method calls.
.SH "CACHE::CACHE VERSUS CHI"
.IX Header "CACHE::CACHE VERSUS CHI"
Cache::Cache is in wide use and very stable, but has not changed in years
and is no longer actively developed.
.PP
\&\s-1CHI\s0 is the successor to Cache::Cache. It adheres to the basic
Cache::Cache \s-1API\s0 but adds new features and drivers (e.g. FastMmap and
Memcached), improves performance, and addresses limitations in the
Cache::Cache implementation. The authors recommend the use of \s-1CHI\s0 going forward.
.PP
Questions about Cache::Cache and \s-1CHI\s0 may be directed to the perl-cache
mailing list at http://groups.google.com/group/perl\-cache\-discuss.
.SH "USAGE"
.IX Header "USAGE"
First, choose the best type of cache implementation for your needs.
The simplest cache is the MemoryCache, which is suitable for
applications that are serving multiple sequential requests, and wish
to avoid making redundant expensive queries, such as an
Apache/mod_perl application talking to a database.  If you wish to
share that data between processes, then perhaps the SharedMemoryCache
is appropriate, although its behavior is tightly bound to the
underlying \s-1IPC\s0 mechanism, which varies from system to system, and is
unsuitable for large objects or large numbers of objects.  When the
SharedMemoryCache is not acceptable, then FileCache offers all of the
same functionality with similar performance metrics, and it is not
limited in terms of the number of objects or their size.  If you wish
to maintain a strict limit on the size of a file system based cache,
then the SizeAwareFileCache is the way to go.  Similarly, the
SizeAwareMemoryCache and the SizeAwareSharedMemoryCache add size
management functionality to the MemoryCache and SharedMemoryCache
classes respectively.
.PP
Using a cache is simple.  Here is some sample code for instantiating
and using a file system based cache.
.PP
.Vb 1
\&  use Cache::FileCache;
\&
\&  my $cache = new Cache::FileCache( );
\&
\&  my $customer = $cache\->get( $name );
\&
\&  if ( not defined $customer )
\&  {
\&    $customer = get_customer_from_db( $name );
\&    $cache\->set( $name, $customer, "10 minutes" );
\&  }
\&
\&  return $customer;
.Ve
.SH "CONSTANTS"
.IX Header "CONSTANTS"
.ie n .IP "\fI\fI$EXPIRES_NEVER\fI\fR" 4
.el .IP "\fI\f(CI$EXPIRES_NEVER\fI\fR" 4
.IX Item "$EXPIRES_NEVER"
The item being set in the cache will never expire.
.ie n .IP "\fI\fI$EXPIRES_NOW\fI\fR" 4
.el .IP "\fI\f(CI$EXPIRES_NOW\fI\fR" 4
.IX Item "$EXPIRES_NOW"
The item being set in the cache will expire immediately.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBClear( )\fR" 4
.IX Item "Clear( )"
Remove all objects from all caches of this type.
.IP "\fBPurge( )\fR" 4
.IX Item "Purge( )"
Remove all objects that have expired from all caches of this type.
.IP "\fBSize( )\fR" 4
.IX Item "Size( )"
Returns the total size of all objects in all caches of this type.
.ie n .IP "\fBnew( \fB$options_hash_ref\fB )\fR" 4
.el .IP "\fBnew( \f(CB$options_hash_ref\fB )\fR" 4
.IX Item "new( $options_hash_ref )"
Construct a new instance of a Cache::Cache. \fI\f(CI$options_hash_ref\fI\fR is a
reference to a hash containing configuration options; see the section
\&\s-1OPTIONS\s0 below.
.IP "\fBclear(  )\fR" 4
.IX Item "clear( )"
Remove all objects from the namespace associated with this cache instance.
.ie n .IP "\fBget( \fB$key\fB )\fR" 4
.el .IP "\fBget( \f(CB$key\fB )\fR" 4
.IX Item "get( $key )"
Returns the data associated with \fI\f(CI$key\fI\fR.
.ie n .IP "\fBget_object( \fB$key\fB )\fR" 4
.el .IP "\fBget_object( \f(CB$key\fB )\fR" 4
.IX Item "get_object( $key )"
Returns the underlying Cache::Object object used to store the cached
data associated with \fI\f(CI$key\fI\fR.  This will not trigger a removal
of the cached object even if the object has expired.
.IP "\fBpurge(  )\fR" 4
.IX Item "purge( )"
Remove all objects that have expired from the namespace associated
with this cache instance.
.ie n .IP "\fBremove( \fB$key\fB )\fR" 4
.el .IP "\fBremove( \f(CB$key\fB )\fR" 4
.IX Item "remove( $key )"
Delete the data associated with the \fI\f(CI$key\fI\fR from the cache.
.ie n .IP "\fBset( \fB$key\fB, \f(BI$data\fB, [$expires_in] )\fR" 4
.el .IP "\fBset( \f(CB$key\fB, \f(CB$data\fB, [$expires_in] )\fR" 4
.IX Item "set( $key, $data, [$expires_in] )"
Associates \fI\f(CI$data\fI\fR with \fI\f(CI$key\fI\fR in the cache. \fI\f(CI$expires_in\fI\fR
indicates the time in seconds until this data should be erased, or the
constant \f(CW$EXPIRES_NOW\fR, or the constant \f(CW$EXPIRES_NEVER\fR.  Defaults to
\&\f(CW$EXPIRES_NEVER\fR.  This variable can also be in the extended format of
\&\*(L"[number] [unit]\*(R", e.g., \*(L"10 minutes\*(R".  The valid units are s, second,
seconds, sec, m, minute, minutes, min, h, hour, hours, d, day, days, w,
week, weeks, M, month, months, y, year, and years.  Additionally,
\&\f(CW$EXPIRES_NOW\fR can be represented as \*(L"now\*(R" and \f(CW$EXPIRES_NEVER\fR can be
represented as \*(L"never\*(R".
.ie n .IP "\fBset_object( \fB$key\fB, \f(BI$object\fB )\fR" 4
.el .IP "\fBset_object( \f(CB$key\fB, \f(CB$object\fB )\fR" 4
.IX Item "set_object( $key, $object )"
Associates \fI\f(CI$key\fI\fR with Cache::Object \fI\f(CI$object\fI\fR.  Using set_object
(as opposed to set) does not trigger an automatic removal of expired
objects.
.IP "\fBsize(  )\fR" 4
.IX Item "size( )"
Returns the total size of all objects in the namespace associated with
this cache instance.
.IP "\fBget_namespaces( )\fR" 4
.IX Item "get_namespaces( )"
Returns all the namespaces associated with this type of cache.
.SH "OPTIONS"
.IX Header "OPTIONS"
The options are set by passing in a reference to a hash containing any
of the following keys:
.IP "\fInamespace\fR" 4
.IX Item "namespace"
The namespace associated with this cache.  Defaults to \*(L"Default\*(R" if
not explicitly set.
.IP "\fIdefault_expires_in\fR" 4
.IX Item "default_expires_in"
The default expiration time for objects place in the cache.  Defaults
to \f(CW$EXPIRES_NEVER\fR if not explicitly set.
.IP "\fIauto_purge_interval\fR" 4
.IX Item "auto_purge_interval"
Sets the auto purge interval.  If this option is set to a particular
time ( in the same format as the expires_in ), then the purge( )
routine will be called during the first set after the interval
expires.  The interval will then be reset.
.IP "\fIauto_purge_on_set\fR" 4
.IX Item "auto_purge_on_set"
If this option is true, then the auto purge interval routine will be
checked on every set.
.IP "\fIauto_purge_on_get\fR" 4
.IX Item "auto_purge_on_get"
If this option is true, then the auto purge interval routine will be
checked on every get.
.SH "PROPERTIES"
.IX Header "PROPERTIES"
.IP "\fB(get|set)_namespace( )\fR" 4
.IX Item "(get|set)_namespace( )"
The namespace of this cache instance
.IP "\fBget_default_expires_in( )\fR" 4
.IX Item "get_default_expires_in( )"
The default expiration time for objects placed in this cache instance
.IP "\fBget_keys( )\fR" 4
.IX Item "get_keys( )"
The list of keys specifying objects in the namespace associated
with this cache instance
.IP "\fBget_identifiers( )\fR" 4
.IX Item "get_identifiers( )"
This method has been deprecated in favor of \fBget_keys( )\fR.
.IP "\fB(get|set)_auto_purge_interval( )\fR" 4
.IX Item "(get|set)_auto_purge_interval( )"
Accesses the auto purge interval.  If this option is set to a particular
time ( in the same format as the expires_in ), then the purge( )
routine will be called during the first get after the interval
expires.  The interval will then be reset.
.IP "\fB(get|set)_auto_purge_on_set( )\fR" 4
.IX Item "(get|set)_auto_purge_on_set( )"
If this property is true, then the auto purge interval routine will be
checked on every set.
.IP "\fB(get|set)_auto_purge_on_get( )\fR" 4
.IX Item "(get|set)_auto_purge_on_get( )"
If this property is true, then the auto purge interval routine will be
checked on every get.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1CHI \-\s0 the successor to Cache::Cache
.PP
Cache::Object, Cache::MemoryCache, Cache::FileCache,
Cache::SharedMemoryCache, and Cache::SizeAwareFileCache
.SH "AUTHOR"
.IX Header "AUTHOR"
Original author: DeWitt Clinton <dewitt@unto.net>
.PP
Last author:     \f(CW$Author:\fR dclinton $
.PP
Copyright (C) 2001\-2003 DeWitt Clinton