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

SYNOPSIS
            use Catalyst qw/
            Cache
        /;

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

        # 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
        These cache operations will call choose_cache_backend with %meta,
        and then call "set", "get", or "remove" on the resulting backend
        object.

    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->{cache} = {
            ...
        };

    All configuration parameters should be provided in a hash reference
    under the "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->{cache}{backends}{small_things} = {
                class    => "Cache::Bounded",
                interval => 1000,
                size     => 10000,
            };
            
    $c->config->{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->{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->{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"

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.

