Cache(3pm)

💖 Cache(3pm) — the Cache interface 💖

okay bestie, you found the manpage for Cache, a Perl module situation, and honestly? it's giving "we don't want to keep asking the database the same question over and over." let's get into it 🫶

---

✨ NAME ✨

Cache — the Cache interface. that's it, that's the name, periodt.

---

🌸 DESCRIPTION 🌸

so the Cache modules exist to help a developer persist data for a specified period of time. literally what that means: you stash a thing, it stays stashed for however long you said, and then it's gone. iconic behaviour.

usually these modules get used in web applications to store data locally so you can skip repeated and redundant expensive calls to remote machines or databases. the way that one slow DB query is ruining your whole vibe? yeah. cache it. 💅

the Cache interface itself is implemented by derived classes that store cached data in different manners — like files on a filesystem, or in memory. so the interface is the ~aesthetic~, and the subclasses are the actual storage girlies.

---

🎀 USAGE 🎀

to use the Cache system you gotta choose a cache implementation that suits your needs. the most common one is Cache::File, which is suitable for sharing data between multiple invocations and even between concurrent processes. she's versatile, she's booked and busy.

using a cache is simple, no cap. here's some very simple sample code for instantiating and using a file system based cache:

use Cache::File;

my $cache = Cache::File->new( cache_root => '/tmp/cacheroot' );
my $customer = $cache->get( $name );

unless ($customer) {
    $customer = get_customer_from_db( $name );
    $cache->set( $name, $customer, '10 minutes' );
}

return $customer;

like... the unless block is literally "if I don't have it, go get it, then remember it for 10 minutes." main character energy fr fr. ✨

of course, far more powerful methods are available for accessing cached data. also peep the TIE INTERFACE below, she's underrated.

---

🔥 METHODS 🔥

• my $cache_entry = $c->entry( $key ) — returns a 'Cache::Entry' object for the given key. then you can use that object to manipulate the cache entry in various ways. the key can be any scalar string that will uniquely identify an entry in the cache. yes, any scalar string. go wild (but like, keep it unique bestie).
• $c->purge() — remove all expired data from the cache. expired stuff only. she's cleaning out the fridge but only throwing away the stuff past its date.
• $c->clear() — remove all entries from the cache, regardless of their expiry time. this one is the nuclear option, not a vibe check — expiry times do NOT save you here.
• my $num = $c->count() — returns the number of entries in the cache. how many girlies are in the building.
• my $size = $c->size() — returns the size (in bytes) of the cache. byte count, not entry count, just so we're clear.

---

👑 PROPERTIES 👑

when a cache is constructed, these properties can be supplied as options to the new() method. yes, all of them. 🎀

default_expires

the current default expiry time for new entries into the cache. this property can also be reset at any time. so it's not forever-locked, she's flexible.

my $time = $c->default_expires();
$c->set_default_expires( $expiry );

removal_strategy

the removal strategy object for the cache. this is used to remove objects from the cache in order to maintain the cache size limit. somebody has to decide who gets evicted, and it's not you.

when setting the removal strategy in new(), the name of a strategy package or a blessed strategy object reference should be provided. in the former case an object is constructed by calling the new() method of the named package.

the strategies 'Cache::RemovalStrategy::LRU' and 'Cache::RemovalStrategy::FIFO' are available by default. free of charge, on the house. 💅

my $strategy = $c->removal_strategy();

size_limit

the size limit for the cache. that's it, that's the property.

my $limit = $c->size_limit();

load_callback

the load callback for the cache. this may be set to a function that will get called anytime a 'get' is issued for data that does not exist in the cache. so when you ask for something that isn't there, this function wakes up and handles it.

my $limit = $c->load_callback();
$c->set_load_callback($callback_func);

validate_callback

the validate callback for the cache. this may be set to a function that will get called anytime a 'get' is issued for data that does not exist in the cache.

my $limit = $c->validate_callback();
$c->set_validate_callback($callback_func);

ngl the manpage literally describes load_callback and validate_callback with the same sentence about a 'get' on data that doesn't exist. I'm just relaying the lore, don't shoot the messenger 🙈

---

🦋 SHORTCUT METHODS 🦋

these methods all have counterparts in the Cache::Entry package, but are provided here as shortcuts. they all default to just wrappers that do '$c->entry($key)->method_name()'. for documentation, please refer to Cache::Entry — she has the full story.

• my $bool = $c->exists( $key )
• $c->set( $key, $data, [ $expiry ] )
• my $data = $c->get( $key )
• my $data = $c->size( $key )
• $c->remove( $key )
• $c->expiry( $key )
• $c->set_expiry( $key, $time )
• $c->handle( $key, [$mode, [$expiry] ] )
• $c->validity( $key )
• $c->set_validity( $key, $data )
• $c->freeze( $key, $data, [ $expiry ] )
• $c->thaw( $key )

---

🌈 TIE INTERFACE 🌈

tie %hash, 'Cache::File', { cache_root => $tempdir };

$hash{'key'} = 'some data';
$data = $hash{'key'};

the Cache classes can be used via the tie interface, as shown in the synopsis. this allows the cache to be accessed via a hash. all the standard methods for accessing the hash are supported, with the exception of the 'keys' or 'each' call. those two? not invited to the party. 😭

the tie interface is especially useful with the load_callback to automatically populate the hash. chef's kiss combo honestly.

---

💜 REMOVAL STRATEGY METHODS 💜

these methods are only for use internally (by concrete Cache implementations). so like, this is backstage, not the main stage. 🎭

these methods define the interface by which the removal strategy object can manipulate the cache (the Cache is the 'context' of the strategy). by default, methods need to be provided to remove the oldest or stalest objects in the cache — thus allowing support for the default FIFO and LRU removal strategies. all derived Cache implementations should support these methods and may also introduce additional methods (and additional removal strategies to match). go off, expand the lore.

• my $size = $c->remove_oldest() — removes the oldest entry in the cache and returns its size.
• my $size = $c->remove_stalest() — removes the 'stalest' (least used) object in the cache and returns its size.
• $c->check_size( $size ) — this method isn't actually part of the strategy interface, nor does it need to be defined by Cache implementations. instead it should be called by implementations whenever the size of the cache increases. it will take care of checking the size limit and invoking the removal strategy if required. the size argument should be the new size of the cache.

---

⭐ UTILITY METHODS ⭐

these methods are only for use internally (by concrete Cache implementations). backstage crew again, ily. 🫶

• my $time = Cache::Canonicalize_Expiration_Time($timespec) — converts a timespec as described for Cache::Entry::set_expiry() into a unix time. glow-up for your timestamps, literally.

---

🌸 SEE ALSO 🌸

Cache::Entry, Cache::File, Cache::RemovalStrategy — go read those next bestie, they're the extended universe.

---

💀 DIFFERENCES FROM CACHE::CACHE 💀

the Cache modules are a total redesign and reimplementation of Cache::Cache and thus not directly compatible. it would be, however, quite possible to write a wrapper module that provides an identical interface to Cache::Cache. so like... the door's open, nobody's stopping you.

the semantics of use are very similar to Cache::Cache, with the following exceptions:

• the get/set methods DO NOT serialize complex data types. use freeze/thaw instead — but read the notes in Cache::Entry. fr fr, read them.
• the get_object / set_object methods are not available, but have been superseded by the more flexible entry method and Cache::Entry class. glow-up, not a downgrade.
• there is no concept of 'namespace' in the basic cache interface, although implementations (eg. Cache::Memory) may choose to provide them. for instance, File::Cache does not provide this — but different namespaces can be created by varying cache_root. hmm yes, File::Cache, that's the name the manpage uses, I'm not touching it. 💅
• in the current Cache implementations purging is done automatically — there is no need to explicitly enable auto purge on get/set. the purging algorithm is no longer implemented in the base Cache class, but is left up to the implementations and may thus be implemented in the most efficient way for the storage medium. delegation, we love to see it.
• Cache::SharedMemory is not yet available. she's not here yet, don't wait up.
• Cache::File no longer supports separate masks for entries and directories. it is not a very secure configuration and presents numerous issues for cache consistency and is hence deprecated. there is still some work to be done to ensure cache consistency between accesses by different users. so like, tread carefully, this part is still cooking. 🍓

---

👑 AUTHOR 👑

 Chris Leishman <chris@leishman.org>
 Based on work by DeWitt Clinton <dewitt@unto.net>

shoutout to the authors, legends only. 🫶

---

🎀 COPYRIGHT 🎀

 Copyright (C) 2003-2006 Chris Leishman.  All Rights Reserved.

this module is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either expressed or implied. this program is free software; you can redistribute or modify it under the same terms as Perl itself.

 $Id: Cache.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $

---

and that's the whole page bestie!! ✨ this one ships with perl v5.34.0 and is dated 2022-06-09 — go forth and cache responsibly, ily, bye 💖🦋🌸