Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  CATALYST::PLUGIN::CACHE (3)

.ds Aq ’


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



        use Catalyst qw/

    # 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 => [],
        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 );


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.


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.



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 <B>curried cache objectB>. 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.


    $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  =>,

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:


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.


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.


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.


Yuval Kogman,

Jos Boumans,


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.


Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 444: Expected text after =item, not a bullet
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 CATALYST::PLUGIN::CACHE (3) 2013-02-25

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.