Provided by: libcatalyst-plugin-cache-perl_0.12-3_all bug

NAME

       Catalyst::Plugin::Cache - Flexible caching support for Catalyst.

SYNOPSIS

               use Catalyst qw/
               Cache
           /;

           # configure a backend or use a store plugin
           __PACKAGE__->config->{'Plugin::Cache'}{backend} = {
               class => "Cache::Bounded",
               # ... params for Cache::Bounded...
           };

           # typical example for Cache::Memcached::libmemcached
           __PACKAGE__->config->{'Plugin::Cache'}{backend} = {
               class   => "Cache::Memcached::libmemcached",
               servers => ['127.0.0.1:11211'],
               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 );
               }
           };

DESCRIPTION

       This plugin gives you access to a variety of systems for caching data. It allows you to
       use a very simple configuration API, while maintaining the possibility of flexibility when
       you need it later.

       Among its features are support for multiple backends, segmentation based on component or
       controller, keyspace partitioning, and so more, in various subsidiary plugins.

METHODS

       cache $profile_name
       cache %meta
           Return a curried object with metadata from $profile_name or as explicitly specified.

           If a profile by the name $profile_name 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.

           This method can also be called without arguments, in which case is treated as though
           the %meta hash was empty.

           See "METADATA" for details.

       curry_cache %meta
           Return a Catalyst::Plugin::Cache::Curried object, curried with %meta.

           See "METADATA" for details.

       cache_set $key, $value, %meta
       cache_get $key, %meta
       cache_remove $key, %meta
       cache_compute $key, $code, %meta
           These cache operations will call choose_cache_backend with %meta, and then call "set",
           "get", "remove", or "compute" on the resulting backend object.

           If the backend object does not support "compute" 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
           CHI.

       choose_cache_backend %meta
           Select a backend object. This should return undef if no specific backend was selected
           - its caller will handle getting "default_cache_backend" on its own.

           This method is typically used by plugins.

       get_cache_backend $name
           Get a backend object by name.

       default_cache_backend
           Return the default backend object.

       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.

METADATA

   Introduction
       Whenever you set or retrieve a key you may specify additional metadata that will be used
       to select a specific backend.

       This metadata is very freeform, and the only key that has any meaning by default is the
       "backend" key which can be used to explicitly choose a backend by name.

       The "choose_cache_backend" 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.

       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.

       However, this is generally left as a hook for larger, more complex applications. Most
       configurations should make due XXXX

       The simplest way to dynamically select a backend is based on the "Cache Profiles"
       configuration.

   Meta Data Keys
       "choose_cache_backend" is called with some default keys.

       key Supplied by "cache_get", "cache_set", and "cache_remove".

       value
           Supplied by "cache_set".

       caller
           The package name of the innermost caller that doesn't match "qr/Plugin::Cache/".

       caller_frame
           The entire "caller($i)" frame of "caller".

       component
           The package name of the innermost caller who "isa" Catalyst::Component.

       component_frame
           This entire "caller($i)" frame of "component".

       controller
           The package name of the innermost caller who "isa" Catalyst::Controller.

       controller_frame
           This entire "caller($i)" frame of "controller".

   Metadata Currying
       In order to avoid specifying %meta over and over again you may call "cache" or
       "curry_cache" with %meta once, and get back a curried cache object. This object responds
       to the methods "get", "set", and "remove", by appending its captured metadata and
       delegating them to "cache_get", "cache_set", and "cache_remove".

       This is simpler than it sounds.

       Here is an example using currying:

           my $cache = $c->cache( %meta ); # cache is curried

           $cache->set( $key, $value );

           $cache->get( $key );

       And here is an example without using currying:

           $c->cache_set( $key, $value, %meta );

           $c->cache_get( $key, %meta );

       See Catalyst::Plugin::Cache::Curried for details.

CONFIGURATION

           $c->config->{'Plugin::Cache'} = {
               ...
           };

       All configuration parameters should be provided in a hash reference under the
       "Plugin::Cache" key in the "config" hash.

   Backend Configuration
       Configuring backend objects is done by adding hash entries under the "backends" key in the
       main config.

       A special case is that the hash key under the "backend" (singular) key of the main config
       is assumed to be the backend named "default".

       class
           Instantiate a backend from a Cache compatible class. E.g.

               $c->config->{'Plugin::Cache'}{backends}{small_things} = {
                   class    => "Cache::Bounded",
                   interval => 1000,
                   size     => 10000,
               };

               $c->config->{'Plugin::Cache'}{backends}{large_things} = {
                   class => "Cache::Memcached",
                   data  => '1.2.3.4:1234',
               };

           The options in the hash are passed to the class's "new" method.

           The class will be "required" as necessary during setup time.

       store
           Instantiate a backend using a store plugin, e.g.

               $c->config->{'Plugin::Cache'}{backend} = {
                   store => "FastMmap",
               };

           Store plugins typically require less configuration because they are specialized for
           Catalyst applications. For example Catalyst::Plugin::Cache::Store::FastMmap will
           specify a default "share_file", and additionally use a subclass of Cache::FastMmap
           that can also store non reference data.

           The store plugin must be loaded.

   Cache Profiles
       profiles
           Supply your own predefined profiles for cache metadata, when using the "cache" method.

           For example when you specify

               $c->config->{'Plugin::Cache'}{profiles}{thumbnails} = {
                   backend => "large_things",
               };

           And then get a cache object like this:

               $c->cache("thumbnails");

           It is the same as if you had done:

               $c->cache( backend => "large_things" );

   Miscellaneous Configuration
       default_store
           When you do not specify a "store" parameter in the backend configuration this one will
           be used instead. This configuration parameter is not necessary if only one store
           plugin is loaded.

TERMINOLOGY

       backend
           An object that responds to the methods detailed in Catalyst::Plugin::Cache::Backend
           (or more).

       store
           A plugin that provides backends of a certain type. This is a bit like a factory.

       cache
           Stored key/value pairs of data for easy re-access.

       metadata
           "Extra" information about the item being stored, which can be used to locate an
           appropriate backend.

       curried cache
             my $cache = $c->cache(type => 'thumbnails');
             $cache->set('pic01', $thumbnaildata);

           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.

           An object that responds to "get", "set", and "remove", and will automatically add
           metadata to calls to "$c->cache_get", etc.

SEE ALSO

       Cache - the generic cache API on CPAN.

       Catalyst::Plugin::Cache::Store - how to write a store plugin.

       Catalyst::Plugin::Cache::Curried - the interface for curried caches.

       Catalyst::Plugin::Cache::Choose::KeyRegexes - choose a backend based on regex matching on
       the keys. Can be used to partition the keyspace.

       Catalyst::Plugin::Cache::ControllerNamespacing - wrap backend objects in a name mangler so
       that every controller gets its own keyspace.

AUTHOR

       Yuval Kogman, "nothingmuch@woobling.org"

       Jos Boumans, "kane@cpan.org"

COPYRIGHT & LICENSE

       Copyright (c) Yuval Kogman, 2006. All rights reserved.

       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 MIT license.