.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
..
.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
.\" ========================================================================
.\"
.IX Title "Catalyst::Plugin::Cache 3pm"
.TH Catalyst::Plugin::Cache 3pm "2021-01-04" "perl v5.32.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"
Catalyst::Plugin::Cache \- Flexible caching support for Catalyst.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&        use Catalyst qw/
\&        Cache
\&    /;
\&
\&    # configure a backend or use a store plugin 
\&    _\|_PACKAGE_\|_\->config\->{\*(AqPlugin::Cache\*(Aq}{backend} = {
\&        class => "Cache::Bounded",
\&        # ... params for Cache::Bounded...
\&    };
\&
\&    # typical example for Cache::Memcached::libmemcached
\&    _\|_PACKAGE_\|_\->config\->{\*(AqPlugin::Cache\*(Aq}{backend} = {
\&        class   => "Cache::Memcached::libmemcached",
\&        servers => [\*(Aq127.0.0.1:11211\*(Aq],
\&        debug   => 2,
\&    };
\&
\&
\&    # In a controller:
\&
\&    sub foo : Local {
\&        my ( $self, $c, $id ) = @_;
\&
\&        my $cache = $c\->cache;
\&
\&        my $result;
\&
\&        unless ( $result = $cache\->get( $id ) ) {
\&            # ... calculate result ...
\&            $c\->cache\->set( $id, $result );
\&        }
\&    };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This plugin gives you access to a variety of systems for caching
data. It allows you to use a very simple configuration \s-1API,\s0 while
maintaining the possibility of flexibility when you need it later.
.PP
Among its features are support for multiple backends, segmentation based
on component or controller, keyspace partitioning, and so more, in
various subsidiary plugins.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "cache $profile_name" 4
.el .IP "cache \f(CW$profile_name\fR" 4
.IX Item "cache $profile_name"
.PD 0
.ie n .IP "cache %meta" 4
.el .IP "cache \f(CW%meta\fR" 4
.IX Item "cache %meta"
.PD
Return a curried object with metadata from \f(CW$profile_name\fR or as
explicitly specified.
.Sp
If a profile by the name \f(CW$profile_name\fR doesn't exist, but a backend
object by that name does exist, the backend will be returned instead,
since the interface for curried caches and backends is almost identical.
.Sp
This method can also be called without arguments, in which case is
treated as though the \f(CW%meta\fR hash was empty.
.Sp
See \*(L"\s-1METADATA\*(R"\s0 for details.
.ie n .IP "curry_cache %meta" 4
.el .IP "curry_cache \f(CW%meta\fR" 4
.IX Item "curry_cache %meta"
Return a Catalyst::Plugin::Cache::Curried object, curried with \f(CW%meta\fR.
.Sp
See \*(L"\s-1METADATA\*(R"\s0 for details.
.ie n .IP "cache_set $key, $value, %meta" 4
.el .IP "cache_set \f(CW$key\fR, \f(CW$value\fR, \f(CW%meta\fR" 4
.IX Item "cache_set $key, $value, %meta"
.PD 0
.ie n .IP "cache_get $key, %meta" 4
.el .IP "cache_get \f(CW$key\fR, \f(CW%meta\fR" 4
.IX Item "cache_get $key, %meta"
.ie n .IP "cache_remove $key, %meta" 4
.el .IP "cache_remove \f(CW$key\fR, \f(CW%meta\fR" 4
.IX Item "cache_remove $key, %meta"
.ie n .IP "cache_compute $key, $code, %meta" 4
.el .IP "cache_compute \f(CW$key\fR, \f(CW$code\fR, \f(CW%meta\fR" 4
.IX Item "cache_compute $key, $code, %meta"
.PD
These cache operations will call choose_cache_backend with \f(CW%meta\fR, and
then call \f(CW\*(C`set\*(C'\fR, \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`remove\*(C'\fR, or \f(CW\*(C`compute\*(C'\fR on the resulting backend
object.
.Sp
If the backend object does not support \f(CW\*(C`compute\*(C'\fR then we emulate it by
calling cache_get, and if the returned value is undefined we call the passed
code reference, stores the returned value with cache_set, and then returns
the value.  Inspired by \s-1CHI\s0.
.ie n .IP "choose_cache_backend %meta" 4
.el .IP "choose_cache_backend \f(CW%meta\fR" 4
.IX Item "choose_cache_backend %meta"
Select a backend object. This should return undef if no specific backend
was selected \- its caller will handle getting \f(CW\*(C`default_cache_backend\*(C'\fR
on its own.
.Sp
This method is typically used by plugins.
.ie n .IP "get_cache_backend $name" 4
.el .IP "get_cache_backend \f(CW$name\fR" 4
.IX Item "get_cache_backend $name"
Get a backend object by name.
.IP "default_cache_backend" 4
.IX Item "default_cache_backend"
Return the default backend object.
.IP "temporary_cache_backend" 4
.IX Item "temporary_cache_backend"
When no default cache backend is configured this method might return a
backend known to work well with the current Catalyst::Engine. This is
a stub.
.SH "METADATA"
.IX Header "METADATA"
.SS "Introduction"
.IX Subsection "Introduction"
Whenever you set or retrieve a key you may specify additional metadata
that will be used to select a specific backend.
.PP
This metadata is very freeform, and the only key that has any meaning by
default is the \f(CW\*(C`backend\*(C'\fR key which can be used to explicitly choose a backend
by name.
.PP
The \f(CW\*(C`choose_cache_backend\*(C'\fR method can be overridden in order to
facilitate more intelligent backend selection. For example,
Catalyst::Plugin::Cache::Choose::KeyRegexes overrides that method to
select a backend based on key regexes.
.PP
Another example is a Catalyst::Plugin::Cache::ControllerNamespacing,
which wraps backends in objects that perform key mangling, in order to
keep caches namespaced per controller.
.PP
However, this is generally left as a hook for larger, more complex
applications. Most configurations should make due \s-1XXXX\s0
.PP
The simplest way to dynamically select a backend is based on the
\&\*(L"Cache Profiles\*(R" configuration.
.SS "Meta Data Keys"
.IX Subsection "Meta Data Keys"
\&\f(CW\*(C`choose_cache_backend\*(C'\fR is called with some default keys.
.IP "key" 4
.IX Item "key"
Supplied by \f(CW\*(C`cache_get\*(C'\fR, \f(CW\*(C`cache_set\*(C'\fR, and \f(CW\*(C`cache_remove\*(C'\fR.
.IP "value" 4
.IX Item "value"
Supplied by \f(CW\*(C`cache_set\*(C'\fR.
.IP "caller" 4
.IX Item "caller"
The package name of the innermost caller that doesn't match
\&\f(CW\*(C`qr/Plugin::Cache/\*(C'\fR.
.IP "caller_frame" 4
.IX Item "caller_frame"
The entire \f(CW\*(C`caller($i)\*(C'\fR frame of \f(CW\*(C`caller\*(C'\fR.
.IP "component" 4
.IX Item "component"
The package name of the innermost caller who \f(CW\*(C`isa\*(C'\fR
Catalyst::Component.
.IP "component_frame" 4
.IX Item "component_frame"
This entire \f(CW\*(C`caller($i)\*(C'\fR frame of \f(CW\*(C`component\*(C'\fR.
.IP "controller" 4
.IX Item "controller"
The package name of the innermost caller who \f(CW\*(C`isa\*(C'\fR
Catalyst::Controller.
.IP "controller_frame" 4
.IX Item "controller_frame"
This entire \f(CW\*(C`caller($i)\*(C'\fR frame of \f(CW\*(C`controller\*(C'\fR.
.SS "Metadata Currying"
.IX Subsection "Metadata Currying"
In order to avoid specifying \f(CW%meta\fR over and over again you may call
\&\f(CW\*(C`cache\*(C'\fR or \f(CW\*(C`curry_cache\*(C'\fR with \f(CW%meta\fR once, and get back a \fBcurried
cache object\fR. This object responds to the methods \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`set\*(C'\fR, and
\&\f(CW\*(C`remove\*(C'\fR, by appending its captured metadata and delegating them to
\&\f(CW\*(C`cache_get\*(C'\fR, \f(CW\*(C`cache_set\*(C'\fR, and \f(CW\*(C`cache_remove\*(C'\fR.
.PP
This is simpler than it sounds.
.PP
Here is an example using currying:
.PP
.Vb 1
\&    my $cache = $c\->cache( %meta ); # cache is curried
\&
\&    $cache\->set( $key, $value );
\&
\&    $cache\->get( $key );
.Ve
.PP
And here is an example without using currying:
.PP
.Vb 1
\&    $c\->cache_set( $key, $value, %meta );
\&
\&    $c\->cache_get( $key, %meta );
.Ve
.PP
See Catalyst::Plugin::Cache::Curried for details.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
.Vb 3
\&    $c\->config\->{\*(AqPlugin::Cache\*(Aq} = {
\&        ...
\&    };
.Ve
.PP
All configuration parameters should be provided in a hash reference
under the \f(CW\*(C`Plugin::Cache\*(C'\fR key in the \f(CW\*(C`config\*(C'\fR hash.
.SS "Backend Configuration"
.IX Subsection "Backend Configuration"
Configuring backend objects is done by adding hash entries under the
\&\f(CW\*(C`backends\*(C'\fR key in the main config.
.PP
A special case is that the hash key under the \f(CW\*(C`backend\*(C'\fR (singular) key
of the main config is assumed to be the backend named \f(CW\*(C`default\*(C'\fR.
.IP "class" 4
.IX Item "class"
Instantiate a backend from a Cache compatible class. E.g.
.Sp
.Vb 5
\&    $c\->config\->{\*(AqPlugin::Cache\*(Aq}{backends}{small_things} = {
\&        class    => "Cache::Bounded",
\&        interval => 1000,
\&        size     => 10000,
\&    };
\&    
\&    $c\->config\->{\*(AqPlugin::Cache\*(Aq}{backends}{large_things} = {
\&        class => "Cache::Memcached",
\&        data  => \*(Aq1.2.3.4:1234\*(Aq,
\&    };
.Ve
.Sp
The options in the hash are passed to the class's \f(CW\*(C`new\*(C'\fR method.
.Sp
The class will be \f(CW\*(C`required\*(C'\fR as necessary during setup time.
.IP "store" 4
.IX Item "store"
Instantiate a backend using a store plugin, e.g.
.Sp
.Vb 3
\&    $c\->config\->{\*(AqPlugin::Cache\*(Aq}{backend} = {
\&        store => "FastMmap",
\&    };
.Ve
.Sp
Store plugins typically require less configuration because they are
specialized for Catalyst applications. For example
Catalyst::Plugin::Cache::Store::FastMmap will specify a default
\&\f(CW\*(C`share_file\*(C'\fR, and additionally use a subclass of Cache::FastMmap
that can also store non reference data.
.Sp
The store plugin must be loaded.
.SS "Cache Profiles"
.IX Subsection "Cache Profiles"
.IP "profiles" 4
.IX Item "profiles"
Supply your own predefined profiles for cache metadata, when using the
\&\f(CW\*(C`cache\*(C'\fR method.
.Sp
For example when you specify
.Sp
.Vb 3
\&    $c\->config\->{\*(AqPlugin::Cache\*(Aq}{profiles}{thumbnails} = {
\&        backend => "large_things",
\&    };
.Ve
.Sp
And then get a cache object like this:
.Sp
.Vb 1
\&    $c\->cache("thumbnails");
.Ve
.Sp
It is the same as if you had done:
.Sp
.Vb 1
\&    $c\->cache( backend => "large_things" );
.Ve
.SS "Miscellaneous Configuration"
.IX Subsection "Miscellaneous Configuration"
.IP "default_store" 4
.IX Item "default_store"
When you do not specify a \f(CW\*(C`store\*(C'\fR parameter in the backend
configuration this one will be used instead. This configuration
parameter is not necessary if only one store plugin is loaded.
.SH "TERMINOLOGY"
.IX Header "TERMINOLOGY"
.IP "backend" 4
.IX Item "backend"
An object that responds to the methods detailed in
Catalyst::Plugin::Cache::Backend (or more).
.IP "store" 4
.IX Item "store"
A plugin that provides backends of a certain type. This is a bit like a
factory.
.IP "cache" 4
.IX Item "cache"
Stored key/value pairs of data for easy re-access.
.IP "metadata" 4
.IX Item "metadata"
\&\*(L"Extra\*(R" information about the item being stored, which can be used to
locate an appropriate backend.
.IP "curried cache" 4
.IX Item "curried cache"
.Vb 2
\&  my $cache = $c\->cache(type => \*(Aqthumbnails\*(Aq);
\&  $cache\->set(\*(Aqpic01\*(Aq, $thumbnaildata);
.Ve
.Sp
A cache which has been pre-configured with a particular set of
namespacing data. In the example the cache returned could be one
specifically tuned for storing thumbnails.
.Sp
An object that responds to \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`set\*(C'\fR, and \f(CW\*(C`remove\*(C'\fR, and will
automatically add metadata to calls to \f(CW\*(C`$c\->cache_get\*(C'\fR, etc.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Cache \- the generic cache \s-1API\s0 on \s-1CPAN.\s0
.PP
Catalyst::Plugin::Cache::Store \- how to write a store plugin.
.PP
Catalyst::Plugin::Cache::Curried \- the interface for curried caches.
.PP
Catalyst::Plugin::Cache::Choose::KeyRegexes \- choose a backend based on
regex matching on the keys. Can be used to partition the keyspace.
.PP
Catalyst::Plugin::Cache::ControllerNamespacing \- wrap backend objects in a
name mangler so that every controller gets its own keyspace.
.SH "AUTHOR"
.IX Header "AUTHOR"
Yuval Kogman, \f(CW\*(C`nothingmuch@woobling.org\*(C'\fR
.PP
Jos Boumans, \f(CW\*(C`kane@cpan.org\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) Yuval Kogman, 2006. All rights reserved.
.PP
This library is free software, you can redistribute it and/or modify it under
the same terms as Perl itself, as well as under the terms of the \s-1MIT\s0 license.