Poet::Cache(3pm)

💖 Poet::Cache — Poet caching with CHI 💖

okay bestie, gather round, because this one is literally the plug for all your caching needs in Poet. Poet::Cache is giving main character energy, and honestly? It ate. ✨

---

✨ SYNOPSIS ✨

First things first, you gotta tell it where to put stuff — conf file style:

# In a conf file...
cache:
   defaults:
      driver: Memcached
      servers: ["10.0.0.15:11211", "10.0.0.15:11212"]

Then you grab your handle, depending on where you're standing:

# In a script...
use Poet::Script qw($cache);

# In a module...
use Poet qw($cache);

# In a component...
my $cache = $m->cache;

# For an arbitrary namespace...
my $cache = Poet::Cache->new(namespace => 'Some::Namespace')

and then, the moment you've been waiting for, actual caching:

# then...
my $customer = $cache->get($name);
if ( !defined $customer ) {
    $customer = get_customer_from_db($name);
    $cache->set( $name, $customer, "10 minutes" );
}
my $customer2 = $cache->compute($name2, "10 minutes", sub {
    get_customer_from_db($name2)
});

See? Get, check, compute, slay. 💅

---

🌸 DESCRIPTION 🌸

Poet::Cache is a subclass of CHI, no cap. And CHI is the icon that gives you one unified caching API over a whole buffet of storage backends: memory, plain files, memory mapped files, memcached, and DBI. Pick your fighter, honestly.

And here's the tea: every single package and every Mason component gets its own CHI namespace, so your caches stay completely separate from each other. No cross-contamination, no drama. 🫶

---

🎀 CONFIGURATION 🎀

So the Poet configuration entry cache, if it exists at all, gets passed straight to Poet::Cache->config(). You can drop it in any Poet conf file you want — like "local.cfg" or "global/cache.cfg", whichever fits your vibe.

Here's a lil baby config that caches everything to files under "data/cache". And plot twist: this is ALSO the default if you show up with no configuration at all. It's the fallback bestie. 🍓

cache:
   defaults:
      driver: File
      root_dir: ${root}/data/cache

Now here's the glow-up version — a more involved config that defines several "storage types" and assigns each namespace its own storage type. Look at her go:

cache:
   defaults:
      expires_variance: 0.2
   storage:
      file:
         driver: File
         root_dir: ${root}/data/cache
      memcached:
         driver: Memcached
         servers: ["10.0.0.15:11211", "10.0.0.15:11212"]
         compress_threshold: 4096
   namespace:
      /some/component:       { storage: file, expires_in: 5min }
      /some/other/component: { storage: memcached, expires_in: 1h }
      Some::Library:         { storage: memcached, expires_in: 10min }

Given the configuration above, and this code right here:

package Some::Library;
use Poet qw($cache);

this $cache will be created with properties:

driver: Memcached
servers: ["10.0.0.15:11211", "10.0.0.15:11212"]
compress_threshold: 4096
expires_in: 10min

periodt. It just knows. 👑

---

🦋 USAGE 🦋

Obtaining cache handle

Where you are determines how you get your handle, and also what your namespace ends up being. It's giving ✨situational✨:

• In a script (namespace will be 'main'):

use Poet::Script qw($cache);

• In a module "MyApp::Foo" (namespace will be 'MyApp::Foo'):

use Poet qw($cache);

• In a component "/foo/bar" (namespace will be '/foo/bar'):

my $cache = $m->cache;

• Manually for an arbitrary namespace:

my $cache = Poet::Cache->new(namespace => 'Some::Namespace');

# or

my $cache = MyApp::Cache->new(category => 'Some::Namespace');

Using cache handle

Now you actually use the thing. Get it, and if it's not there, go get it from the db and set it. Classic:

my $customer = $cache->get($name);
if ( !defined $customer ) {
    $customer = get_customer_from_db($name);
    $cache->set( $name, $customer, "10 minutes" );
}
my $customer2 = $cache->compute($name2, "10 minutes", sub {
    get_customer_from_db($name2)
});

If you want the whole lore, go read CHI and Mason::Plugin::Cache for more details. iykyk. 📚

---

🔥 MODIFIABLE METHODS 🔥

heads up bestie: these methods are not meant to be called from the outside. They're here so you can override them or hit them with method modifiers in subclasses. Internal business only. 🙈

• initialize_caching — Called exactly once, when the Poet environment is initialized. By default it calls "__PACKAGE__->config" with the configuration entry 'cache'. That's it, that's the whole job. 👑

---

💜 SEE ALSO 💜

• Poet

---

🌈 AUTHOR 🌈

Jonathan Swartz <swartz@pobox.com> — we stan. 🫶

---

⭐ COPYRIGHT AND LICENSE ⭐

This software is copyright (c) 2012 by Jonathan Swartz.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. fr fr, go wild, just keep the same terms. 💖

---

and that's the whole page, bestie!! this one came to you courtesy of perl v5.34.0, dated 2022-06-18 — shoutout to the Poet::Cache(3pm) era, we love her, we miss her, we still use her. mwah 💅✨🎀