.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "CHI 3pm"
.TH CHI 3pm "2017-07-31" "perl v5.26.0" "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"
CHI \- Unified cache handling interface
.SH "VERSION"
.IX Header "VERSION"
version 0.60
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use CHI;
\&
\&    # Choose a standard driver
\&    #
\&    my $cache = CHI\->new( driver => \*(AqMemory\*(Aq, global => 1 );
\&    my $cache = CHI\->new( driver => \*(AqRawMemory\*(Aq, global => 1 );
\&    my $cache = CHI\->new( driver => \*(AqFile\*(Aq,
\&        root_dir => \*(Aq/path/to/root\*(Aq
\&    );
\&    my $cache = CHI\->new( driver => \*(AqFastMmap\*(Aq,
\&        root_dir   => \*(Aq/path/to/root\*(Aq,
\&        cache_size => \*(Aq1k\*(Aq
\&    );
\&    my $cache = CHI\->new( driver  => \*(AqMemcached::libmemcached\*(Aq,
\&        servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
\&        l1_cache => { driver => \*(AqFastMmap\*(Aq, root_dir => \*(Aq/path/to/root\*(Aq }
\&    );
\&    my $cache = CHI\->new( driver => \*(AqDBI\*(Aq,
\&        dbh => $dbh
\&    );
\&    my $cache = CHI\->new( driver => \*(AqBerkeleyDB\*(Aq,
\&        root_dir => \*(Aq/path/to/root\*(Aq
\&    );
\&
\&    # Create your own driver
\&    # 
\&    my $cache = CHI\->new( driver => \*(Aq+My::Special::Driver\*(Aq, ... );
\&
\&    # Cache operations
\&    #
\&    my $customer = $cache\->get($name);
\&    if ( !defined $customer ) {
\&        $customer = get_customer_from_db($name);
\&        $cache\->set( $name, $customer, "10 minutes" );
\&    }
\&    my $customer2 = $cache\->compute($name2, "10 minutes", sub {
\&        get_customer_from_db($name2)
\&    });
\&    $cache\->remove($name);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1CHI\s0 provides a unified caching \s-1API,\s0 designed to assist a developer in
persisting data for a specified period of time.
.PP
The \s-1CHI\s0 interface is implemented by driver classes that support fetching,
storing and clearing of data. Driver classes exist or will exist for the gamut
of storage backends available to Perl, such as memory, plain files, memory
mapped files, memcached, and \s-1DBI.\s0
.PP
\&\s-1CHI\s0 is intended as an evolution of DeWitt Clinton's
Cache::Cache package, adhering to the basic Cache \s-1API\s0 but
adding new features and addressing limitations in the Cache::Cache
implementation.
.SH "FEATURES"
.IX Header "FEATURES"
.IP "\(bu" 4
Easy to create new drivers
.IP "\(bu" 4
Uniform support for namespaces
.IP "\(bu" 4
Automatic serialization of keys and values
.IP "\(bu" 4
Multilevel caches
.IP "\(bu" 4
Probabilistic expiration and busy locks, to reduce cache miss stampedes
.IP "\(bu" 4
Optional logging and statistics collection of cache activity
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
To create a new cache object, call \f(CW\*(C`<CHI\->new\*(C'\fR. It takes the common
options listed below. \fIdriver\fR is required; all others are optional.
.PP
Some drivers will take additional constructor options. For example, the File
driver takes \f(CW\*(C`root_dir\*(C'\fR and \f(CW\*(C`depth\*(C'\fR options.
.PP
You can configure default options for each new cache object created \- see
\&\*(L"\s-1SUBCLASSING AND CONFIGURING CHI\*(R"\s0.
.PP
Note that \f(CW\*(C`CHI\->new\*(C'\fR returns an instance of a subclass of
CHI::Driver, not \f(CW\*(C`CHI\*(C'\fR.
.IP "compress_threshold [\s-1INT\s0]" 4
.IX Item "compress_threshold [INT]"
A value in bytes. Automatically compress values larger than this before
storing.  Requires Compress::Zlib to be installed. Defaults
to undef, meaning no automatic compression. Inspired by the parameter of the
same name in Cache::Memcached.
.Sp
.Vb 2
\&    # Compress values larger than 1MB
\&    compress_threshold => 1024*1024
.Ve
.IP "driver [\s-1STRING\s0]" 4
.IX Item "driver [STRING]"
Required. The name of a cache driver, for example \*(L"Memory\*(R" or \*(L"File\*(R".  \s-1CHI\s0 will
prefix the string with \*(L"CHI::Driver::\*(R", unless it begins with '+'. e.g.
.Sp
.Vb 2
\&    driver => \*(AqFile\*(Aq;                   # uses CHI::Driver::File
\&    driver => \*(Aq+My::CHI::Driver::File\*(Aq  # uses My::CHI::Driver::File
.Ve
.IP "expires_in [\s-1DURATION\s0], expires_at [\s-1INT\s0], expires_variance [\s-1FLOAT\s0]" 4
.IX Item "expires_in [DURATION], expires_at [INT], expires_variance [FLOAT]"
Provide default values for the corresponding \*(L"set\*(R" options.
.IP "expires_on_backend [\s-1NUM\s0]" 4
.IX Item "expires_on_backend [NUM]"
If set to 0 (the default), \s-1CHI\s0 alone is aware of the expiration time and does
not pass it along to the backend driver. This allows you to use \*(L"get_object\*(R"
to retrieve expired items.
.Sp
If set to 1, pass expiration times to backend driver if the driver supports it
\&\*(-- for example, CHI::Driver::Memcached and
CHI::Driver::CacheCache. This may allow the driver to better
manage its space and evict items. Note that only simple expiration time will be
passed along, e.g. not \*(L"expires_variance\*(R".
.Sp
If set to a number greater than 1 (e.g. 1.25), the time until expiration will
be multiplied by that number before being passed to the backend driver. This
gives you a customizable window of opportunity to retrieve expired items.
.IP "key_digester [STRING|HASHREF|OBJECT]" 4
.IX Item "key_digester [STRING|HASHREF|OBJECT]"
Digest algorithm to use on keys longer than \*(L"max_key_length\*(R" \- e.g. \*(L"\s-1MD5\*(R",
\&\*(L"SHA\-1\*(R",\s0 or \*(L"\s-1SHA\-256\*(R".\s0
.Sp
Can be a Digest object, or a string or hashref which will passed to
Digest\->\fInew()\fR. You will need to ensure Digest is installed to use these
options.
.Sp
Default is \*(L"\s-1MD5\*(R".\s0
.IP "key_serializer [STRING|HASHREF|OBJECT]" 4
.IX Item "key_serializer [STRING|HASHREF|OBJECT]"
An object to use for serializing keys that are references. See \*(L"serializer\*(R"
above for the different ways this can be passed in. The default is to use the
\&\s-1JSON\s0 backend in canonical mode (sorted hash keys).
.IP "label [\s-1STRING\s0]" 4
.IX Item "label [STRING]"
A label for the cache as a whole, independent of namespace \- e.g.
\&\*(L"web-file-cache\*(R". Used when referring to the cache in logs,
statistics, and error messages. By default, set to
\&\*(L"short_driver_name\*(R".
.IP "l1_cache [\s-1HASHREF\s0]" 4
.IX Item "l1_cache [HASHREF]"
Add an L1 cache as a subcache. See \*(L"\s-1SUBCACHES\*(R"\s0.
.IP "max_key_length [\s-1INT\s0]" 4
.IX Item "max_key_length [INT]"
Keys over this size will be digested. The default is
driver-specific; CHI::Driver::File, for example, defaults this to 240
due to file system limits. For most drivers there is no maximum.
.IP "mirror_cache [\s-1HASHREF\s0]" 4
.IX Item "mirror_cache [HASHREF]"
Add an mirror cache as a subcache. See \*(L"\s-1SUBCACHES\*(R"\s0.
.IP "namespace [\s-1STRING\s0]" 4
.IX Item "namespace [STRING]"
Identifies a namespace that all cache entries for this object will be in. This
allows easy separation of multiple, distinct caches without worrying about key
collision.
.Sp
Suggestions for easy namespace selection:
.RS 4
.IP "\(bu" 4
In a class, use the class name:
.Sp
.Vb 1
\&    my $cache = CHI\->new(namespace => _\|_PACKAGE_\|_, ...);
.Ve
.IP "\(bu" 4
In a script, use the script's absolute path name:
.Sp
.Vb 2
\&    use Cwd qw(realpath);
\&    my $cache = CHI\->new(namespace => realpath($0), ...);
.Ve
.IP "\(bu" 4
In a web template, use the template name. For example, in Mason, \f(CW$m\fR\->cache
will set the namespace to the current component path.
.RE
.RS 4
.Sp
Defaults to 'Default' if not specified.
.RE
.IP "on_get_error [STRING|CODEREF]" 4
.IX Item "on_get_error [STRING|CODEREF]"
.PD 0
.IP "on_set_error [STRING|CODEREF]" 4
.IX Item "on_set_error [STRING|CODEREF]"
.PD
How to handle runtime errors occurring during cache gets and cache sets, which
may or may not be considered fatal in your application. Options are:
.RS 4
.IP "\(bu" 4
log (the default) \- log an error, or ignore if no logger is set \- see
\&\*(L"\s-1LOGGING\*(R"\s0
.IP "\(bu" 4
ignore \- do nothing
.IP "\(bu" 4
warn \- call \fIwarn()\fR with an appropriate message
.IP "\(bu" 4
die \- call \fIdie()\fR with an appropriate message
.IP "\(bu" 4
\&\fIcoderef\fR \- call this code reference with three arguments: an appropriate
message, the key, and the original raw error message
.RE
.RS 4
.RE
.IP "serializer [STRING|HASHREF|OBJECT]" 4
.IX Item "serializer [STRING|HASHREF|OBJECT]"
An object to use for serializing data before storing it in the cache, and
deserializing data after retrieving it from the cache. Only references will be
serialized; plain scalars will be placed in the cache as-is.
.Sp
If this is a string, a Data::Serializer object will be
created, with the string passed as the 'serializer' option and raw=1. Common
options include 'Storable', 'Data::Dumper', and '\s-1YAML\s0'. If this is a hashref,
Data::Serializer will be called with the hash. You
will need to ensure Data::Serializer is installed to use these options.
.Sp
Otherwise, this must be a Data::Serializer object or
another object that implements \fI\fIserialize()\fI\fR and \fI\fIdeserialize()\fI\fR.
.Sp
e.g.
.Sp
.Vb 2
\&    # Serialize using raw Data::Dumper
\&    my $cache = CHI\->new(serializer => \*(AqData::Dumper\*(Aq);
\&
\&    # Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex\-encoded
\&    my $cache = CHI\->new(serializer => { serializer => \*(AqData::Dumper\*(Aq, compress => 1 });
\&
\&    # Serialize using custom object
\&    my $cache = CHI\->new(serializer => My::Custom::Serializer\->new())
.Ve
.Sp
The default is to use raw Storable.
.IP "traits [\s-1LISTREF\s0]" 4
.IX Item "traits [LISTREF]"
List of one or more roles to apply to the \f(CW\*(C`CHI::Driver\*(C'\fR class that is
constructed. The roles will automatically be prefixed with
\&\f(CW\*(C`CHI::Driver::Role::\*(C'\fR unless preceded with a '+'. e.g.
.Sp
.Vb 1
\&    traits => [\*(AqStoresAccessedAt\*(Aq, \*(Aq+My::CHI::Driver::Role\*(Aq]
.Ve
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
The following methods can be called on any cache handle returned from
\&\s-1CHI\-\s0>\fInew()\fR. They are implemented in the CHI::Driver package.
.SS "Getting and setting"
.IX Subsection "Getting and setting"
.ie n .IP "get( $key, [option => value, ...] )" 4
.el .IP "get( \f(CW$key\fR, [option => value, ...] )" 4
.IX Item "get( $key, [option => value, ...] )"
Returns the data associated with \fI\f(CI$key\fI\fR. If \fI\f(CI$key\fI\fR does not exist or has
expired, returns undef. Expired items are not automatically removed and may be
examined with \*(L"get_object\*(R" or \*(L"get_expires_at\*(R".
.Sp
\&\fI\f(CI$key\fI\fR may be followed by one or more name/value parameters:
.RS 4
.IP "expire_if [\s-1CODEREF\s0]" 4
.IX Item "expire_if [CODEREF]"
If \fI\f(CI$key\fI\fR exists and has not expired, call code reference with the
CHI::CacheObject and CHI::Driver as the
parameters. If code returns a true value, \f(CW\*(C`get\*(C'\fR returns undef as if the item
were expired. For example, to treat the cache as expired if \fI\f(CI$file\fI\fR has
changed since the value was computed:
.Sp
.Vb 1
\&    $cache\->get(\*(Aqfoo\*(Aq, expire_if => sub { $_[0]\->created_at < (stat($file))[9] });
.Ve
.IP "busy_lock [\s-1DURATION\s0]" 4
.IX Item "busy_lock [DURATION]"
If the value has expired, the get will still return undef, but the expiration
time of the cache entry will be set to the current time plus the specified
duration.  This is used to prevent multiple processes
from recomputing the same expensive value simultaneously. The problem with this
technique is that it doubles the number of writes performed \- see
\&\*(L"expires_variance\*(R" for another technique.
.IP "obj_ref [\s-1SCALARREF\s0]" 4
.IX Item "obj_ref [SCALARREF]"
If the item exists in cache (even if expired), place the
CHI::CacheObject object in the provided \s-1SCALARREF.\s0
.RE
.RS 4
.RE
.ie n .IP "set( $key, $data, [$expires_in | ""now"" | ""never"" | options] )" 4
.el .IP "set( \f(CW$key\fR, \f(CW$data\fR, [$expires_in | ``now'' | ``never'' | options] )" 4
.IX Item "set( $key, $data, [$expires_in | now | never | options] )"
Associates \fI\f(CI$data\fI\fR with \fI\f(CI$key\fI\fR in the cache, overwriting any existing entry.
Returns \fI\f(CI$data\fI\fR.
.Sp
The third argument to \f(CW\*(C`set\*(C'\fR is optional, and may be either a scalar or a hash
reference. If it is a scalar, it may be the string \*(L"now\*(R", the string \*(L"never\*(R",
or else a duration treated as an \fIexpires_in\fR value described below. If it is
a hash reference, it may contain one or more of the following options. Most of
these options can be provided with defaults in the cache constructor.
.RS 4
.IP "expires_in [\s-1DURATION\s0]" 4
.IX Item "expires_in [DURATION]"
Amount of time from now until this data expires. \fI\s-1DURATION\s0\fR may be an integer
number of seconds or a duration expression.
.IP "expires_at [\s-1INT\s0]" 4
.IX Item "expires_at [INT]"
The epoch time at which the data expires.
.IP "expires_variance [\s-1FLOAT\s0]" 4
.IX Item "expires_variance [FLOAT]"
Controls the variable expiration feature, which allows items to expire a little
earlier than the stated expiration time to help prevent cache miss stampedes.
.Sp
Value is between 0.0 and 1.0, with 0.0 meaning that items expire exactly when
specified (feature is disabled), and 1.0 meaning that items might expire
anytime from now until the stated expiration time. The default is 0.0. A
setting of 0.10 to 0.25 would introduce a small amount of variation without
interfering too much with intended expiration times.
.Sp
The probability of expiration increases as a function of how far along we are
in the potential expiration window, with the probability being near 0 at the
beginning of the window and approaching 1 at the end.
.Sp
For example, in all of the following cases, an item might be considered expired
any time between 15 and 20 minutes, with about a 20% chance at 16 minutes, a
40% chance at 17 minutes, and a 100% chance at 20 minutes.
.Sp
.Vb 3
\&    my $cache = CHI\->new ( ..., expires_variance => 0.25, ... );
\&    $cache\->set($key, $value, \*(Aq20 min\*(Aq);
\&    $cache\->set($key, $value, { expires_at => time() + 20*60 });
\&
\&    my $cache = CHI\->new ( ... );
\&    $cache\->set($key, $value, { expires_in => \*(Aq20 min\*(Aq, expires_variance => 0.25 });
.Ve
.Sp
\&\s-1CHI\s0 will make a new probabilistic choice every time it needs to know whether an
item has expired (i.e. it does not save the results of its determination), so
you can get situations like this:
.Sp
.Vb 2
\&    my $value = $cache\->get($key);     # returns undef (indicating expired)
\&    my $value = $cache\->get($key);     # returns valid value this time!
\&
\&    if ($cache\->is_valid($key))        # returns undef (indicating expired)
\&    if ($cache\->is_valid($key))        # returns true this time!
.Ve
.Sp
Typical applications won't be affected by this, since the object is recomputed
as soon as it is determined to be expired. But it's something to be aware of.
.RE
.RS 4
.RE
.ie n .IP "compute( $key, $options, $code )" 4
.el .IP "compute( \f(CW$key\fR, \f(CW$options\fR, \f(CW$code\fR )" 4
.IX Item "compute( $key, $options, $code )"
Combines the \f(CW\*(C`get\*(C'\fR and \f(CW\*(C`set\*(C'\fR operations in a single call. Attempts to get
\&\fI\f(CI$key\fI\fR; if successful, returns the value. Otherwise, calls \fI\f(CI$code\fI\fR and uses
the return value as the new value for \fI\f(CI$key\fI\fR, which is then returned. Caller
context (scalar or list) is respected.
.Sp
\&\fI\f(CI$options\fI\fR can be undef, a scalar, or a hash reference. If it is undef, it has
no effect. If it is a scalar, it is treated as the \f(CW\*(C`expires_in\*(C'\fR duration and
passed as the third argument to \f(CW\*(C`set\*(C'\fR. If it is a hash reference, it may
contain name/value pairs for both \f(CW\*(C`get\*(C'\fR and \f(CW\*(C`set\*(C'\fR.  e.g.
.Sp
.Vb 4
\&    # No expiration
\&    my $value = $cache\->compute($key, undef, sub {
\&        # compute and return value for $key here
\&    });
\&
\&    # Expire in 5 minutes
\&    my $value = $cache\->compute($key, \*(Aq5min\*(Aq, sub {
\&        # compute and return value for $key here
\&    });
\&
\&    # Expire in 5 minutes or when a particular condition occurs
\&    my $value = $cache\->compute($key,
\&        { expires_in => \*(Aq5min\*(Aq, expire_if => sub { ... } },
\&        sub {
\&           # compute and return value for $key here
\&    });
\&
\&    # List context
\&    my @value = $cache\->compute($key, \*(Aq5min\*(Aq, sub {
\&        ...
\&        return @some_list;
\&    });
.Ve
.Sp
This method will eventually support the ability to recompute a value in the
background just before it actually expires, so that users are not impacted by
recompute time.
.Sp
Note: Prior to version 0.40, the last two arguments were in reverse order; both
will be accepted for backward compatibility. We think the coderef looks better
at the end.
.SS "Removing and expiring"
.IX Subsection "Removing and expiring"
.ie n .IP "remove( $key )" 4
.el .IP "remove( \f(CW$key\fR )" 4
.IX Item "remove( $key )"
Remove the data associated with the \fI\f(CI$key\fI\fR from the cache.
.ie n .IP "expire( $key )" 4
.el .IP "expire( \f(CW$key\fR )" 4
.IX Item "expire( $key )"
If \fI\f(CI$key\fI\fR exists, expire it by setting its expiration time into the past. Does
not necessarily remove the data. Since this involves essentially setting the
value again, \f(CW\*(C`remove\*(C'\fR may be more efficient for some drivers.
.SS "Inspecting keys"
.IX Subsection "Inspecting keys"
.ie n .IP "is_valid( $key )" 4
.el .IP "is_valid( \f(CW$key\fR )" 4
.IX Item "is_valid( $key )"
Returns a boolean indicating whether \fI\f(CI$key\fI\fR exists in the cache and has not
expired. Note: Expiration may be determined probabilistically if
\&\*(L"expires_variance\*(R" was used.
.ie n .IP "exists_and_is_expired( $key )" 4
.el .IP "exists_and_is_expired( \f(CW$key\fR )" 4
.IX Item "exists_and_is_expired( $key )"
Returns a boolean indicating whether \fI\f(CI$key\fI\fR exists in the cache and has
expired.  Note: Expiration may be determined probabilistically if
\&\*(L"expires_variance\*(R" was used.
.ie n .IP "get_expires_at( $key )" 4
.el .IP "get_expires_at( \f(CW$key\fR )" 4
.IX Item "get_expires_at( $key )"
Returns the epoch time at which \fI\f(CI$key\fI\fR definitively expires. Returns undef if
the key does not exist or it has no expiration time.
.ie n .IP "get_object( $key )" 4
.el .IP "get_object( \f(CW$key\fR )" 4
.IX Item "get_object( $key )"
Returns a CHI::CacheObject object containing data about the
entry associated with \fI\f(CI$key\fI\fR, or undef if no such key exists. The object will
be returned even if the entry has expired, as long as it has not been removed.
.SS "Atomic operations (\s-1ALPHA\s0)"
.IX Subsection "Atomic operations (ALPHA)"
These methods combine both reading and writing of a cache entry in a single
operation. The names and behaviors were adapted from
memcached <http://memcached.org/>.
.PP
Some drivers (e.g.
CHI::Driver::Memcached::libmemcached,
CHI::Driver::DBI) may implement these as truly atomic operations, and
will be documented thusly.  The default implementations are not atomic: the get
and set occur discretely and another process could potentially modify the cache
in between them.
.PP
These operations are labeled \s-1ALPHA\s0 because we haven't yet figured out how they
integrate with other \s-1CHI\s0 features, in particular \*(L"\s-1SUBCACHES\*(R"\s0. APIs and
behavior may change.
.ie n .IP "add( $key, $data, [$expires_in | ""now"" | ""never"" | options] )" 4
.el .IP "add( \f(CW$key\fR, \f(CW$data\fR, [$expires_in | ``now'' | ``never'' | options] )" 4
.IX Item "add( $key, $data, [$expires_in | now | never | options] )"
Do a set, but only if \fI\f(CI$key\fI\fR is not valid in the cache.
.ie n .IP "replace( $key, $data, [$expires_in | ""now"" | ""never"" | options] )" 4
.el .IP "replace( \f(CW$key\fR, \f(CW$data\fR, [$expires_in | ``now'' | ``never'' | options] )" 4
.IX Item "replace( $key, $data, [$expires_in | now | never | options] )"
Do a set, but only if \fI\f(CI$key\fI\fR is valid in the cache.
.ie n .IP "append( $key, $new_data)" 4
.el .IP "append( \f(CW$key\fR, \f(CW$new_data\fR)" 4
.IX Item "append( $key, $new_data)"
Append \fI\f(CI$new_data\fI\fR to whatever value is currently associated with \fI\f(CI$key\fI\fR. Has
no effect if \fI\f(CI$key\fI\fR does not exist in the cache.
.Sp
Returns true if \fI\f(CI$key\fI\fR was in the cache, false otherwise.
.Sp
This is intended for simple string values only. For efficiency's sake, \s-1CHI\s0
won't attempt to check for, or handle, the case where data is
serialized or compressed; the new data will
simply be appended, and an error will most probably occur when you try to
retrieve the value.
.Sp
Does not modify expiration or other metadata. If \fI\f(CI$key\fI\fR exists but is expired,
it will remain expired.
.Sp
If you use a driver with the non-atomic (default) implementation, some appends
may be lost due to race conditions.
.SS "Namespace operations"
.IX Subsection "Namespace operations"
.IP "clear( )" 4
.IX Item "clear( )"
Remove all entries from the namespace.
.IP "get_keys( )" 4
.IX Item "get_keys( )"
Returns a list of keys in the namespace. This may or may not include expired
keys, depending on the driver.
.Sp
The keys may not look the same as they did when passed into \*(L"set\*(R"; they may
have been serialized, utf8 encoded, and/or digested (see \*(L"\s-1KEY AND VALUE
TRANSFORMATIONS\*(R"\s0). However, they may still be passed back into \*(L"get\*(R",
\&\*(L"set\*(R", etc. to access the same underlying objects. i.e. the following code is
guaranteed to produce all key/value pairs from the cache:
.Sp
.Vb 1
\&  map { ($_, $c\->get($_)) } $c\->get_keys()
.Ve
.IP "purge( )" 4
.IX Item "purge( )"
Remove all entries that have expired from the namespace associated with this
cache instance. Warning: May be very inefficient, depending on the number of
keys and the driver.
.IP "get_namespaces( )" 4
.IX Item "get_namespaces( )"
Returns a list of namespaces associated with the cache. This may or may not
include empty namespaces, depending on the driver.
.SS "Multiple key/value operations"
.IX Subsection "Multiple key/value operations"
The methods in this section process multiple keys and/or values at once. By
default these are implemented with the obvious map operations, but some cache
drivers (e.g. Cache::Memcached) can override them with more
efficient implementations.
.ie n .IP "get_multi_arrayref( $keys )" 4
.el .IP "get_multi_arrayref( \f(CW$keys\fR )" 4
.IX Item "get_multi_arrayref( $keys )"
Get the keys in list reference \fI\f(CI$keys\fI\fR, and return a list reference of the
same length with corresponding values or undefs.
.ie n .IP "get_multi_hashref( $keys )" 4
.el .IP "get_multi_hashref( \f(CW$keys\fR )" 4
.IX Item "get_multi_hashref( $keys )"
Like \*(L"get_multi_arrayref\*(R", but returns a hash reference with each key in
\&\fI\f(CI$keys\fI\fR mapping to its corresponding value or undef. Will only work with
scalar keys.
.ie n .IP "set_multi( $key_values, $set_options )" 4
.el .IP "set_multi( \f(CW$key_values\fR, \f(CW$set_options\fR )" 4
.IX Item "set_multi( $key_values, $set_options )"
Set the multiple keys and values provided in hash reference \fI\f(CI$key_values\fI\fR.
\&\fI\f(CI$set_options\fI\fR is a scalar or hash reference, used as the third argument to
set. Will only work with scalar keys.
.ie n .IP "remove_multi( $keys )" 4
.el .IP "remove_multi( \f(CW$keys\fR )" 4
.IX Item "remove_multi( $keys )"
Removes the keys in list reference \fI\f(CI$keys\fI\fR.
.IP "dump_as_hash( )" 4
.IX Item "dump_as_hash( )"
Returns a hash reference containing all the non-expired keys and values in the
cache.
.SS "Property accessors"
.IX Subsection "Property accessors"
.IP "chi_root_class( )" 4
.IX Item "chi_root_class( )"
Returns the name of the root class under which this object was created, e.g.
\&\f(CW\*(C`CHI\*(C'\fR or \f(CW\*(C`My::CHI\*(C'\fR. See \*(L"\s-1SUBCLASSING AND CONFIGURING CHI\*(R"\s0.
.IP "driver_class( )" 4
.IX Item "driver_class( )"
Returns the full name of the driver class. e.g.
.Sp
.Vb 6
\&    CHI\->new(driver=>\*(AqFile\*(Aq)\->driver_class
\&       => CHI::Driver::File
\&    CHI\->new(driver=>\*(Aq+CHI::Driver::File\*(Aq)\->driver_class
\&       => CHI::Driver::File
\&    CHI\->new(driver=>\*(Aq+My::Driver::File\*(Aq)\->driver_class
\&       => My::Driver::File
.Ve
.Sp
You should use this rather than \f(CW\*(C`ref()\*(C'\fR. Due to some subclassing tricks \s-1CHI\s0
employs, the actual class of the object is neither guaranteed nor likely to be
the driver class.
.IP "short_driver_name( )" 4
.IX Item "short_driver_name( )"
Returns the name of the driver class, minus the CHI::Driver:: prefix, if any.
e.g.
.Sp
.Vb 6
\&    CHI\->new(driver=>\*(AqFile\*(Aq)\->short_driver_name
\&       => File
\&    CHI\->new(driver_class=>\*(AqCHI::Driver::File\*(Aq)\->short_driver_name
\&       => File
\&    CHI\->new(driver_class=>\*(AqMy::Driver::File\*(Aq)\->short_driver_name
\&       => My::Driver::File
.Ve
.IP "Standard read-write accessors" 4
.IX Item "Standard read-write accessors"
.Vb 6
\&    expires_in
\&    expires_at
\&    expires_variance
\&    label
\&    on_get_error
\&    on_set_error
.Ve
.IP "Standard read-only accessors" 4
.IX Item "Standard read-only accessors"
.Vb 2
\&    namespace
\&    serializer
.Ve
.SS "Deprecated methods"
.IX Subsection "Deprecated methods"
The following methods are deprecated and will be removed in a later version:
.PP
.Vb 1
\&    is_empty
.Ve
.SH "DURATION EXPRESSIONS"
.IX Header "DURATION EXPRESSIONS"
Duration expressions, which appear in the \*(L"set\*(R" command and various other
parts of the \s-1API,\s0 are parsed by Time::Duration::Parse.
A duration is either a plain number, which is treated like a number of seconds,
or a number and a string representing time units where the string is one of:
.PP
.Vb 7
\&    s second seconds sec secs
\&    m minute minutes min mins
\&    h hr hour hours
\&    d day days
\&    w week weeks
\&    M month months
\&    y year years
.Ve
.PP
e.g. the following are all valid duration expressions:
.PP
.Vb 5
\&    25
\&    3s
\&    5 seconds
\&    1 minute and ten seconds
\&    1 hour
.Ve
.SH "KEY AND VALUE TRANSFORMATIONS"
.IX Header "KEY AND VALUE TRANSFORMATIONS"
\&\s-1CHI\s0 strives to accept arbitrary keys and values for caching regardless of the
limitations of the underlying driver.
.SS "Key transformations"
.IX Subsection "Key transformations"
.IP "\(bu" 4
Keys that are references are serialized \- see \*(L"key_serializer\*(R".
.IP "\(bu" 4
Keys with wide (>255) characters are utf8 encoded.
.IP "\(bu" 4
Keys exceeding the maximum length for the underlying driver are digested \- see
\&\*(L"max_key_length\*(R" and \*(L"key_digester\*(R".
.IP "\(bu" 4
For some drivers (e.g. CHI::Driver::File), keys containing special
characters or whitespace are escaped with URL-like escaping.
.PP
Note: All transformations above with the exception of escaping are \fIone-way\fR,
meaning that \s-1CHI\s0 does not attempt to undo them when returned from \*(L"get_keys\*(R";
and \fIidempotent\fR, meaning that applying them a second time has no effect. So
when you call \*(L"get_keys\*(R", the key you get may not be exactly what you passed
in, but you'll be able to pass that key in to get the corresponding object.
.SS "Value transformations"
.IX Subsection "Value transformations"
.IP "\(bu" 4
Values which are references are automatically serialized before storing, and
deserialized after retrieving \- see \*(L"serializer\*(R".
.IP "\(bu" 4
Values with their utf8 flag on are utf8 encoded before storing, and utf8
decoded after retrieving.
.SH "SUBCACHES"
.IX Header "SUBCACHES"
It is possible to a cache to have one or more \fIsubcaches\fR. There are currently
two types of subcaches: \fIL1\fR and \fImirror\fR.
.SS "L1 cache"
.IX Subsection "L1 cache"
An L1 (or \*(L"level one\*(R") cache sits in front of the primary cache, usually to
provide faster access for commonly accessed cache entries. For example, this
places an in-process Memory cache in front of a Memcached cache:
.PP
.Vb 5
\&    my $cache = CHI\->new(
\&        driver   => \*(AqMemcached\*(Aq,
\&        servers  => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
\&        l1_cache => { driver => \*(AqMemory\*(Aq, global => 1, max_size => 1024*1024 }
\&    );
.Ve
.PP
On a \f(CW\*(C`get\*(C'\fR, the L1 cache is checked first \- if a valid value exists, it is
returned. Otherwise, the primary cache is checked \- if a valid value exists, it
is returned, and the value is placed in the L1 cache with the same expiration
time. In this way, items fetched most frequently from the primary cache will
tend to be in the L1 cache.
.PP
\&\f(CW\*(C`set\*(C'\fR operations are distributed to both the primary and L1 cache.
.PP
You can access the L1 cache with the \f(CW\*(C`l1_cache\*(C'\fR method. For example, this
clears the L1 cache but leaves the primary cache intact:
.PP
.Vb 1
\&    $cache\->l1_cache\->clear();
.Ve
.SS "Mirror cache"
.IX Subsection "Mirror cache"
A mirror cache is a write-only cache that, over time, mirrors the content of
the primary cache. \f(CW\*(C`set\*(C'\fR operations are distributed to both the primary and
mirror cache, but \f(CW\*(C`get\*(C'\fR operations go only to the primary cache.
.PP
Mirror caches are useful when you want to migrate from one cache to another.
You can populate a mirror cache and switch over to it once it is sufficiently
populated. For example, here we migrate from an old to a new cache directory:
.PP
.Vb 5
\&    my $cache = CHI\->new(
\&        driver          => \*(AqFile\*(Aq,
\&        root_dir        => \*(Aq/old/cache/root\*(Aq,
\&        mirror_cache => { driver => \*(AqFile\*(Aq, root_dir => \*(Aq/new/cache/root\*(Aq },
\&    );
.Ve
.PP
We leave this running for a few hours (or as needed), then replace it with
.PP
.Vb 4
\&    my $cache = CHI\->new(
\&        driver   => \*(AqFile\*(Aq,
\&        root_dir => \*(Aq/new/cache/root\*(Aq
\&    );
.Ve
.PP
You can access the mirror cache with the \f(CW\*(C`mirror_cache\*(C'\fR method. For example,
to see how many keys have made it over to the mirror cache:
.PP
.Vb 1
\&    my @keys = $cache\->mirror_cache\->get_keys();
.Ve
.SS "Creating subcaches"
.IX Subsection "Creating subcaches"
As illustrated above, you create subcaches by passing the \f(CW\*(C`l1_cache\*(C'\fR and/or
\&\f(CW\*(C`mirror_cache\*(C'\fR option to the \s-1CHI\s0 constructor. These options, in turn, should
contain a hash of options to create the subcache with.
.PP
The cache containing the subcache is called the \fIparent cache\fR.
.PP
The following options are automatically inherited by the subcache from the
parent cache, and may not be overridden:
.PP
.Vb 4
\&    expires_at
\&    expires_in
\&    expires_variance
\&    serializer
.Ve
.PP
(Reason: for efficiency, we want to create a single cache
object and store it in both caches. The cache object contains
expiration information and is dependent on the serializer.  At some point we
could conceivably add code that will use a single object or separate objects as
necessary, and thus allow the above to be overridden.)
.PP
The following options are automatically inherited by the subcache from the
parent cache, but may be overridden:
.PP
.Vb 3
\&    namespace
\&    on_get_error
\&    on_set_error
.Ve
.PP
All other options are initialized in the subcache as normal, irrespective of
their values in the parent.
.PP
It is not currently possible to pass an existing cache in as a subcache.
.SS "Common subcache behaviors"
.IX Subsection "Common subcache behaviors"
These behaviors hold regardless of the type of subcache.
.PP
The following methods are distributed to both the primary cache and subcache:
.PP
.Vb 4
\&    clear
\&    expire
\&    purge
\&    remove
.Ve
.PP
The following methods return information solely from the primary cache.
However, you are free to call them explicitly on the subcache. (Trying to merge
in subcache information automatically would require too much guessing about the
caller's intent.)
.PP
.Vb 7
\&    get_keys
\&    get_namespaces
\&    get_object
\&    get_expires_at
\&    exists_and_is_expired
\&    is_valid
\&    dump_as_hash
.Ve
.SS "Multiple subcaches"
.IX Subsection "Multiple subcaches"
It is valid for a cache to have one of each kind of subcache, e.g. an L1 cache
and a mirror cache.
.PP
A cache cannot have more than one of each kind of subcache, but a subcache can
have its own subcaches, and so on. e.g.
.PP
.Vb 9
\&    my $cache = CHI\->new(
\&        driver   => \*(AqMemcached\*(Aq,
\&        servers  => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
\&        l1_cache => {
\&            driver     => \*(AqFile\*(Aq,
\&            root_dir   => \*(Aq/path/to/root\*(Aq,
\&            l1_cache   => { driver => \*(AqRawMemory\*(Aq, global => 1 }
\&        }
\&    );
.Ve
.SS "Methods for parent caches"
.IX Subsection "Methods for parent caches"
.IP "has_subcaches( )" 4
.IX Item "has_subcaches( )"
Returns a boolean indicating whether this cache has subcaches.
.IP "l1_cache( )" 4
.IX Item "l1_cache( )"
Returns the L1 cache for this cache, if any. Can only be called if
\&\fIhas_subcaches\fR is true.
.IP "mirror_cache( )" 4
.IX Item "mirror_cache( )"
Returns the mirror cache for this cache, if any. Can only be called if
\&\fIhas_subcaches\fR is true.
.IP "subcaches( )" 4
.IX Item "subcaches( )"
Returns the subcaches for this cache, in arbitrary order. Can only be called if
\&\fIhas_subcaches\fR is true.
.SS "Methods for subcaches"
.IX Subsection "Methods for subcaches"
.IP "is_subcache( )" 4
.IX Item "is_subcache( )"
Returns a boolean indicating whether this is a subcache.
.IP "subcache_type( )" 4
.IX Item "subcache_type( )"
Returns the type of subcache as a string, e.g. 'l1_cache' or 'mirror_cache'.
Can only be called if \fIis_subcache\fR is true.
.IP "parent_cache( )" 4
.IX Item "parent_cache( )"
Returns the parent cache (weakened to prevent circular reference).  Can only be
called if \fIis_subcache\fR is true.
.SS "Developing new kinds of subcaches"
.IX Subsection "Developing new kinds of subcaches"
At this time, subcache behavior is hardcoded into CHI::Driver, so there is no
easy way to modify the behavior of existing subcache types or create new ones.
We'd like to make this more flexible eventually.
.SH "SIZE AWARENESS"
.IX Header "SIZE AWARENESS"
If \*(L"is_size_aware\*(R" or \*(L"max_size\*(R" are passed to the constructor, the cache
will be \fIsize aware\fR \- that is, it will keep track of its own size (in bytes)
as items are added and removed. You can get a cache's size with \*(L"get_size\*(R".
.PP
Size aware caches generally keep track of their size in a separate meta-key,
and have to do an extra store whenever the size changes (e.g. on each set and
remove).
.SS "Maximum size and discard policies"
.IX Subsection "Maximum size and discard policies"
If a cache's size rises above its \*(L"max_size\*(R", items are discarded until the
cache size is sufficiently below the max size. (See
\&\*(L"max_size_reduction_factor\*(R" for how to fine-tune this.)
.PP
The order in which items are discarded is controlled with \*(L"discard_policy\*(R".
The default discard policy is 'arbitrary', which discards items in an arbitrary
order.  The available policies and default policy can differ with each driver,
e.g. the CHI::Driver::Memory driver provides and defaults to an '\s-1LRU\s0'
policy.
.SS "Appropriate drivers"
.IX Subsection "Appropriate drivers"
Size awareness was chiefly designed for, and works well with, the
CHI::Driver::Memory driver: one often needs to enforce a maximum size
on a memory cache, and the overhead of tracking size in memory is negligible.
However, the capability may be useful with other drivers.
.PP
Some drivers \- for example, CHI::Driver::FastMmap and
CHI::Driver::Memcached \- inherently keep track of their size and
enforce a maximum size, and it makes no sense to turn on \s-1CHI\s0's size awareness
for these.
.PP
Also, for drivers that cannot atomically read and update a value \- for example,
CHI::Driver::File \- there is a race condition in the updating of size
that can cause the size to grow inaccurate over time.
.SH "SUBCLASSING AND CONFIGURING CHI"
.IX Header "SUBCLASSING AND CONFIGURING CHI"
You can subclass \s-1CHI\s0 for your own application and configure it in a variety of
ways, e.g. predefining storage types and defaults for new cache objects. Your
configuration will be independent of the main \s-1CHI\s0 class and other \s-1CHI\s0
subclasses.
.PP
Start with a trivial subclass:
.PP
.Vb 1
\&    package My::CHI;
\&
\&    use base qw(CHI);
\&    1;
.Ve
.PP
Then, just use your subclass in place of \s-1CHI:\s0
.PP
.Vb 1
\&    my $cache = My::CHI\->new( ... );
\&
\&    print $cache\->chi_root_class;
\&       ==> \*(AqMy::CHI\*(Aq
.Ve
.PP
This obviously doesn't change any behavior by itself. Here's an example with
actual config:
.PP
.Vb 1
\&    package My::CHI;
\&
\&    use base qw(CHI);
\&
\&    _\|_PACKAGE_\|_\->config({
\&        storage   => {
\&            local_file => { driver => \*(AqFile\*(Aq, root_dir => \*(Aq/my/root\*(Aq },
\&            memcached  => {
\&                driver  => \*(AqMemcached::libmemcached\*(Aq,
\&                servers => [ \*(Aq10.0.0.15:11211\*(Aq, \*(Aq10.0.0.15:11212\*(Aq ]
\&            },
\&        },
\&        namespace => {
\&            \*(AqFoo\*(Aq => { storage => \*(Aqlocal_file\*(Aq },
\&            \*(AqBar\*(Aq => { storage => \*(Aqlocal_file\*(Aq, depth => 3 },
\&            \*(AqBaz\*(Aq => { storage => \*(Aqmemcached\*(Aq },
\&        }
\&        defaults  => { storage => \*(Aqlocal_file\*(Aq },
\&        memoize_cache_objects => 1,
\&    });
\&
\&    1;
.Ve
.PP
Each of these config keys is explained in the next section.
.SS "Configuration keys"
.IX Subsection "Configuration keys"
.IP "storage" 4
.IX Item "storage"
A map of names to parameter hashrefs. This provides a way to encapsulate common
sets of parameters that might be used in many caches. e.g. if you define
.Sp
.Vb 4
\&    storage => {
\&        local_file => { driver => \*(AqFile\*(Aq, root_dir => \*(Aq/my/root\*(Aq },
\&        ...
\&    }
.Ve
.Sp
then
.Sp
.Vb 2
\&    my $cache = My::CHI\->new
\&       (namespace => \*(AqFoo\*(Aq, storage => \*(Aqlocal_file\*(Aq);
.Ve
.Sp
is equivalent to
.Sp
.Vb 2
\&    my $cache = My::CHI\->new
\&       (namespace => \*(AqFoo\*(Aq, driver => \*(AqFile\*(Aq, root_dir => \*(Aq/my/root\*(Aq);
.Ve
.IP "namespace" 4
.IX Item "namespace"
A map of namespace names to parameter hashrefs. When you create a cache object
with the specified namespace, the hashref of parameters will be applied as
defaults. e.g. if you define
.Sp
.Vb 5
\&    namespace => {
\&        \*(AqFoo\*(Aq => { driver => \*(AqFile\*(Aq, root_dir => \*(Aq/my/root\*(Aq },
\&        \*(AqBar\*(Aq => { storage => \*(Aqdatabase\*(Aq },
\&        ...
\&    }
.Ve
.Sp
then
.Sp
.Vb 4
\&    my $cache1 = My::CHI\->new
\&       (namespace => \*(AqFoo\*(Aq);
\&    my $cache2 = My::CHI\->new
\&       (namespace => \*(AqBar\*(Aq);
.Ve
.Sp
is equivalent to
.Sp
.Vb 4
\&    my $cache1 = My::CHI\->new
\&       (namespace => \*(AqFoo\*(Aq, driver => \*(AqFile\*(Aq, root_dir => \*(Aq/my/root\*(Aq);
\&    my $cache2 = My::CHI\->new
\&       (namespace => \*(AqBar\*(Aq, storage => \*(Aqdatabase\*(Aq);
.Ve
.IP "defaults" 4
.IX Item "defaults"
A hash of parameters that will be used as core defaults for all cache objects
created under this root class. e.g.
.Sp
.Vb 4
\&    defaults => {
\&        on_get_error => \*(Aqdie\*(Aq,
\&        expires_variance => 0.2,
\&    }
.Ve
.Sp
These can be overridden by namespace defaults, storage settings, or \f(CW\*(C`new\*(C'\fR
parameters.
.IP "memoize_cache_objects" 4
.IX Item "memoize_cache_objects"
True or false, indicates whether \f(CW\*(C`My::CHI\->new\*(C'\fR should memoize and return
the same cache object if given the same parameters. This can speed things up if
you create cache objects frequently. Will currently only work for 0\- or 1\- key
parameter hashes. e.g.
.Sp
.Vb 3
\&    My::CHI\->config({
\&        memoize_cache_objects => 1,
\&    });
.Ve
.Sp
then
.Sp
.Vb 5
\&    # $cache1 and $cache2 will be the same object, regardless of what
\&    # namespace and storage defaults are associated with \*(AqFoo\*(Aq
\&    #
\&    my $cache1 = My::CHI\->new(namespace => \*(AqFoo\*(Aq);
\&    my $cache2 = My::CHI\->new(namespace => \*(AqFoo\*(Aq);
\&
\&    # $cache3 and $cache4 will be different objects
\&    #
\&    my $cache3 = My::CHI\->new
\&       (namespace => \*(AqBar\*(Aq, driver => \*(AqFile\*(Aq, root_dir => \*(Aq/my/root\*(Aq);
\&    my $cache4 = My::CHI\->new
\&       (namespace => \*(AqBar\*(Aq, driver => \*(AqFile\*(Aq, root_dir => \*(Aq/my/root\*(Aq);
.Ve
.Sp
To clear the memoized cache objects, call
.Sp
.Vb 1
\&    My::CHI\->clear_memoized_cache_objects;
.Ve
.SS "How defaults are combined"
.IX Subsection "How defaults are combined"
Defaults are applied in the following order, from highest to lowest precedence:
.IP "\(bu" 4
Parameters passed in \f(CW\*(C`new\*(C'\fR
.IP "\(bu" 4
Namespace defaults, if any
.IP "\(bu" 4
Storage settings, if any
.IP "\(bu" 4
Core defaults defined under 'defaults'
.SS "Inheritance of config"
.IX Subsection "Inheritance of config"
A subclass will automatically inherit the configuration of its parent if it
does not call \f(CW\*(C`config\*(C'\fR itself (ala
Class::Data::Inheritable).
.SS "Reading config from a file"
.IX Subsection "Reading config from a file"
.Vb 1
\&    use YAML::XS qw(LoadFile);
\&
\&    _\|_PACKAGE_\|_\->config(LoadFile("/path/to/cache.yml"));
.Ve
.SH "AVAILABILITY OF DRIVERS"
.IX Header "AVAILABILITY OF DRIVERS"
The following drivers are currently available as part of this distribution:
.IP "\(bu" 4
CHI::Driver::Memory \- In-process memory based cache
.IP "\(bu" 4
CHI::Driver::RawMemory \- In-process memory based
cache that stores references directly instead of serializing/deep\-copying
.IP "\(bu" 4
CHI::Driver::File \- File-based cache using one file per
entry in a multi-level directory structure
.IP "\(bu" 4
CHI::Driver::FastMmap \- Shared memory interprocess
cache via mmap'ed files
.IP "\(bu" 4
CHI::Driver::Null \- Dummy cache in which nothing is stored
.IP "\(bu" 4
CHI::Driver::CacheCache \- \s-1CHI\s0 wrapper for
Cache::Cache
.PP
The following drivers are currently available as separate \s-1CPAN\s0 distributions:
.IP "\(bu" 4
CHI::Driver::Memcached \- Distributed memory-based
cache (works with Cache::Memcached,
Cache::Memcached::Fast, and
Cache::Memcached::libmemcached)
.IP "\(bu" 4
CHI::Driver::DBI \- Cache in any DBI-supported database
.IP "\(bu" 4
CHI::Driver::BerkeleyDB \- Cache in BerkeleyDB files
.IP "\(bu" 4
CHI::Driver::Redis \- Cache in Redis <http://redis.io/>
.IP "\(bu" 4
CHI::Driver::SharedMem \- Cache in shared memory
.PP
This list is likely incomplete. A complete set of drivers can be found on \s-1CPAN\s0
by searching for \*(L"CHI::Driver\*(R".
.SH "PERFORMANCE COMPARISON OF DRIVERS"
.IX Header "PERFORMANCE COMPARISON OF DRIVERS"
See CHI::Benchmarks for a comparison of read/write times of both \s-1CHI\s0 and
non-CHI cache implementations.
.PP
\&\f(CW\*(C`etc/bench/bench.pl\*(C'\fR in the \f(CW\*(C`CHI\*(C'\fR distribution contains a script to run these
types of benchmarks on your own system.
.SH "DEVELOPING NEW DRIVERS"
.IX Header "DEVELOPING NEW DRIVERS"
See CHI::Driver::Development for information on
developing new drivers.
.SH "LOGGING"
.IX Header "LOGGING"
\&\f(CW\*(C`CHI\*(C'\fR uses Log::Any for logging events. For example, a debug log
message is sent with category \f(CW\*(C`CHI::Driver\*(C'\fR for every cache get and set.
.PP
See Log::Any documentation for how to control where logs get sent,
if anywhere.
.SH "STATS"
.IX Header "STATS"
\&\s-1CHI\s0 can record statistics, such as number of hits, misses and sets, on a
per-namespace basis and log the results to your Log::Any logger.
You can then use utilities included with this distribution to read stats back
from the logs and report a summary. See CHI::Stats for details.
.SH "RELATION TO OTHER MODULES"
.IX Header "RELATION TO OTHER MODULES"
.SS "Cache::Cache"
.IX Subsection "Cache::Cache"
\&\s-1CHI\s0 is intended as an evolution of DeWitt Clinton's
Cache::Cache package. It starts with the same basic \s-1API\s0 (which
has proven durable over time) but addresses some implementation shortcomings
that cannot be fixed in Cache::Cache due to backward compatibility concerns. 
In particular:
.IP "Performance" 4
.IX Item "Performance"
Some of Cache::Cache's subclasses (e.g. Cache::FileCache)
have been justifiably criticized as inefficient. \s-1CHI\s0 has been designed from the
ground up with performance in mind, both in terms of general overhead and in
the built-in driver classes. Method calls are kept to a minimum, data is only
serialized when necessary, and metadata such as expiration time is stored in
packed binary format alongside the data.
.IP "Ease of subclassing" 4
.IX Item "Ease of subclassing"
New Cache::Cache subclasses can be tedious to create, due to a lack of code
refactoring, the use of non-OO package subroutines, and the separation of
\&\*(L"cache\*(R" and \*(L"backend\*(R" classes. With \s-1CHI,\s0 the goal is to make the creation of
new drivers as easy as possible, roughly the same as writing a \s-1TIE\s0 interface to
your data store.  Concerns like serialization and expiration options are
handled by the driver base class so that individual drivers don't have to worry
about them.
.IP "Increased compatibility with cache implementations" 4
.IX Item "Increased compatibility with cache implementations"
Probably because of the reasons above, Cache::Cache subclasses were never
created for some of the most popular caches available on \s-1CPAN,\s0 e.g.
Cache::FastMmap and Cache::Memcached.
\&\s-1CHI\s0's goal is to be able to support these and other caches with a minimum
performance overhead and minimum of glue code required.
.SS "Cache"
.IX Subsection "Cache"
The Cache distribution is another redesign and implementation of
Cache, created by Chris Leishman in 2003. Like \s-1CHI,\s0 it improves performance and
reduces the barrier to implementing new cache drivers. It breaks with the
Cache::Cache interface in a few ways that I considered non-negotiable \- for
example, get/set do not serialize data, and namespaces are an optional feature
that drivers may decide not to implement.
.SS "Cache::Memcached, Cache::FastMmap, etc."
.IX Subsection "Cache::Memcached, Cache::FastMmap, etc."
\&\s-1CPAN\s0 sports a variety of full-featured standalone cache modules representing
particular backends. \s-1CHI\s0 does not reinvent these but simply wraps them with an
appropriate driver. For example, CHI::Driver::Memcached and
CHI::Driver::FastMmap are thin layers around Cache::Memcached and
Cache::FastMmap.
.PP
Of course, because these modules already work on their own, there will be some
overlap. Cache::FastMmap, for example, already has code to serialize data and
handle expiration times. Here's how \s-1CHI\s0 resolves these overlaps.
.IP "Serialization" 4
.IX Item "Serialization"
\&\s-1CHI\s0 handles its own serialization, passing a flat binary string to the
underlying cache backend. The notable exception is
CHI::Driver::RawMemory which does no serialization.
.IP "Expiration" 4
.IX Item "Expiration"
\&\s-1CHI\s0 packs expiration times (as well as other metadata) inside the binary string
passed to the underlying cache backend. The backend is unaware of these values;
from its point of view the item has no expiration time. Among other things,
this means that you can use \s-1CHI\s0 to examine expired items (e.g. with
\&\f(CW$cache\fR\->get_object) even if this is not supported natively by the backend.
.Sp
At some point \s-1CHI\s0 will provide the option of explicitly notifying the backend
of the expiration time as well. This might allow the backend to do better
storage management, etc., but would prevent \s-1CHI\s0 from examining expired items.
.PP
Naturally, using \s-1CHI\s0's FastMmap or Memcached driver will never be as time or
storage efficient as simply using Cache::FastMmap or Cache::Memcached.  In
terms of performance, we've attempted to make the overhead as small as
possible, on the order of 5% per get or set (benchmarks coming soon). In terms
of storage size, \s-1CHI\s0 adds about 16 bytes of metadata overhead to each item. How
much this matters obviously depends on the typical size of items in your cache.
.SH "SUPPORT AND DOCUMENTATION"
.IX Header "SUPPORT AND DOCUMENTATION"
Questions and feedback are welcome, and should be directed to the perl-cache
mailing list:
.PP
.Vb 1
\&    http://groups.google.com/group/perl\-cache\-discuss
.Ve
.PP
Bugs and feature requests will be tracked at \s-1RT:\s0
.PP
.Vb 2
\&    http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI
\&    bug\-chi@rt.cpan.org
.Ve
.PP
The latest source code can be browsed and fetched at:
.PP
.Vb 2
\&    http://github.com/jonswar/perl\-chi/tree/master
\&    git clone git://github.com/jonswar/perl\-chi.git
.Ve
.SH "ACKNOWLEDGMENTS"
.IX Header "ACKNOWLEDGMENTS"
Thanks to Dewitt Clinton for the original Cache::Cache, to Rob Mueller for the
Perl cache benchmarks, and to Perrin Harkins for the discussions that got this
going.
.PP
\&\s-1CHI\s0 was originally designed and developed for the Digital Media group of the
Hearst Corporation, a diversified media company based in New York City.  Many
thanks to Hearst management for agreeing to this open source release.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Cache::Cache
.SH "AUTHOR"
.IX Header "AUTHOR"
Jonathan Swartz <swartz@pobox.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Jonathan Swartz.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.