Cataly...::Cache(3pm)

💖 Cataly...::Cache — the vibe-y guide 💖

okay bestie, so this is a page from the User Contributed Perl Documentation for Cataly...::Cache(3pm), and I'm gonna walk you through it like we're texting at 2am. grab a boba, we're doing this 🧋✨

---

🌸 NAME 🌸

Catalyst::Plugin::Cache — flexible caching support for Catalyst. that's it, that's the name, slay 💅

---

✨ SYNOPSIS ✨

okay so here's the whole setup, verbatim, no notes:

        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 );
        }
    };

like, look at that. use Catalyst qw/ Cache /; and boom, you have caching. iconic behavior fr fr 🔥

---

🦋 DESCRIPTION 🦋

so basically this plugin hands you access to a whole buffet of systems for caching data. it lets you use a super simple configuration API while still keeping the possibility of flexibility when you need it later — like, lowkey easy now, highkey powerful later.

among its features, bestie:

• support for multiple backends
• segmentation based on component or controller
• keyspace partitioning
• and so more, in various subsidiary plugins

it's giving "everything you wanted, but organized" 💅

---

👑 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 — because the interface for curried caches and backends is almost identical. so it's fine, don't panic 🫶

this method can also be called without arguments, in which case it's treated as though the %meta hash was empty.

see "METADATA" for details, bestie.

💜 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. periodt.

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. no cap 🧢

💜 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. it's giving "I'll do my part, you do yours" 🤝

this method is typically used by plugins.

💜 get_cache_backend $name

get a backend object by name. straightforward. we love a simple queen ✨

💜 default_cache_backend

return the default backend object. the main character of backends, honestly 👑

💜 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. yes, a stub. don't come for me, it's literally what it says 💀

---

🌈 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. that's the one that matters, bestie.

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. cute AND organized 🎀

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

⚠️ yeah, that "XXXX" is in the original. I'm not inventing anything, I'm just the messenger 💀

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. here they all are:

• 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. trust 🙏

here's an example using currying:

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

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

    $cache->get( $key );

and here's 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. that's the rule, bestie 📋

💜 Backend Configuration 💜

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

a special case: the hash key under the "backend" (singular) key of the main config is assumed to be the backend named "default". yes, singular vs plural matters. read it twice, I did 🙈

• 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. don't forget, bestie 🫶

💜 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" );

same energy, less typing. we love efficiency ✨

💜 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"

icons, both of them 👑

---

🌈 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.

---

okay and that's the whole page, bestie 🎀 this came from perl v5.34.0, dated 2022-06-09, so if you're reading this years later, that's the era we're in. go forth and cache responsibly 💖✨🦋