Cache::Cache(3pm)

💖 Cache::Cache — the Cache interface 💖

ok so bestie, you're looking at Cache::Cache(3pm), from the User Contributed Perl Documentation crew, and honestly? it's giving foundational. let me put you on. 🫶

---

✨ NAME ✨

Cache::Cache — the Cache interface. that's it, that's the whole name. iconic brevity. 👑

---

🌸 DESCRIPTION 🌸

so the Cache modules are literally designed to help a developer persist data for a specified period of time. that's the vibe. no cap.

bestie, people mostly use these in web applications to store data locally so they can skip all those repeated and redundant expensive calls to remote machines or databases. like why would you keep hitting the database when you could just... not? 💅

and people have also been known to use Cache::Cache for its straightforward interface when they wanna share data between runs of an application, or between invocations of a CGI-style script, or just as an easy-to-use abstraction of the filesystem or shared memory. so many options, all of them valid.

the Cache::Cache interface is implemented by classes that support the get, set, remove, size, purge, and clear instance methods, plus their corresponding static methods, all for persisting data across method calls. periodt.

---

🦋 CACHE::CACHE VERSUS CHI 🦋

okay so real talk, Cache::Cache is in wide use and very stable, but it has not changed in years and is no longer actively developed. it's in its retirement era and we respect it. 🙈

CHI is the successor to Cache::Cache. it adheres to the basic Cache::Cache API but adds new features and drivers (e.g. FastMmap and Memcached), improves performance, and addresses limitations in the Cache::Cache implementation. the authors recommend the use of CHI going forward. so like... yeah. moving on up. 🔥

questions about Cache::Cache and CHI may be directed to the perl-cache mailing list at http://groups.google.com/group/perl-cache-discuss. they're friendly, go say hi. 🌈

---

🌟 USAGE 🌟

first step, bestie: choose the best type of cache implementation for your needs. it's a whole vibe check.

the simplest cache is the MemoryCache, which is suitable for applications that are serving multiple sequential requests and wish to avoid making redundant expensive queries — like an Apache/mod_perl application talking to a database. classic.

if you wish to share that data between processes, then perhaps the SharedMemoryCache is appropriate, although its behavior is tightly bound to the underlying IPC mechanism, which varies from system to system, and it is unsuitable for large objects or large numbers of objects. so, know your limits, girl.

when the SharedMemoryCache is not acceptable, then FileCache offers all of the same functionality with similar performance metrics, and it is not limited in terms of the number of objects or their size. slay.

if you wish to maintain a strict limit on the size of a file system based cache, then the SizeAwareFileCache is the way to go. similarly, the SizeAwareMemoryCache and the SizeAwareSharedMemoryCache add size management functionality to the MemoryCache and SharedMemoryCache classes respectively. size-aware, self-aware, we love a queen who knows her bounds. 👑

using a cache is simple. here is some sample code for instantiating and using a file system based cache:

use Cache::FileCache;

my $cache = new Cache::FileCache( );

my $customer = $cache->get( $name );

if ( not defined $customer )
{
  $customer = get_customer_from_db( $name );
  $cache->set( $name, $customer, "10 minutes" );
}

return $customer;

---

💎 CONSTANTS 💎

• $EXPIRES_NEVER — the item being set in the cache will never expire. it's forever, fr fr. 💖
• $EXPIRES_NOW — the item being set in the cache will expire immediately. gone. bye. 💀

---

🎀 METHODS 🎀

• Clear( ) — remove all objects from all caches of this type. the big sweep. ✨
• Purge( ) — remove all objects that have expired from all caches of this type. expired stuff only, no extra casualties.
• Size( ) — returns the total size of all objects in all caches of this type. numbers, bestie.
• new( $options_hash_ref ) — construct a new instance of a Cache::Cache. $options_hash_ref is a reference to a hash containing configuration options; see the section OPTIONS below. 👀
• clear( ) — remove all objects from the namespace associated with this cache instance.
• get( $key ) — returns the data associated with $key.
• get_object( $key ) — returns the underlying Cache::Object object used to store the cached data associated with $key. this will not trigger a removal of the cached object even if the object has expired. sneaky but on purpose.
• purge( ) — remove all objects that have expired from the namespace associated with this cache instance.
• remove( $key ) — delete the data associated with the $key from the cache.
• set( $key, $data, [$expires_in] ) — associates $data with $key in the cache. $expires_in indicates the time in seconds until this data should be erased, or the constant $EXPIRES_NOW, or the constant $EXPIRES_NEVER. defaults to $EXPIRES_NEVER. this variable can also be in the extended format of "[number] [unit]", e.g., "10 minutes". the valid units are s, second, seconds, sec, m, minute, minutes, min, h, hour, hours, d, day, days, w, week, weeks, M, month, months, y, year, and years. additionally, $EXPIRES_NOW can be represented as "now" and $EXPIRES_NEVER can be represented as "never". yes, all of those, memorize them, we're not skipping any. 💅
• set_object( $key, $object ) — associates $key with Cache::Object $object. using set_object (as opposed to set) does not trigger an automatic removal of expired objects.
• size( ) — returns the total size of all objects in the namespace associated with this cache instance.
• get_namespaces( ) — returns all the namespaces associated with this type of cache.

---

🌸 OPTIONS 🌸

the options are set by passing in a reference to a hash containing any of the following keys:

• namespace — the namespace associated with this cache. defaults to "Default" if not explicitly set.
• default_expires_in — the default expiration time for objects place in the cache. defaults to $EXPIRES_NEVER if not explicitly set.
• auto_purge_interval — sets the auto purge interval. if this option is set to a particular time ( in the same format as the expires_in ), then the purge( ) routine will be called during the first set after the interval expires. the interval will then be reset. 🔄
• auto_purge_on_set — if this option is true, then the auto purge interval routine will be checked on every set.
• auto_purge_on_get — if this option is true, then the auto purge interval routine will be checked on every get.

---

🦄 PROPERTIES 🦄

• (get|set)_namespace( ) — the namespace of this cache instance.
• get_default_expires_in( ) — the default expiration time for objects placed in this cache instance.
• get_keys( ) — the list of keys specifying objects in the namespace associated with this cache instance.
• get_identifiers( ) — this method has been deprecated in favor of get_keys( ). 🚨 old, retired, do not use, use get_keys instead, bestie.
• (get|set)_auto_purge_interval( ) — accesses the auto purge interval. if this option is set to a particular time ( in the same format as the expires_in ), then the purge( ) routine will be called during the first get after the interval expires. the interval will then be reset.
• (get|set)_auto_purge_on_set( ) — if this property is true, then the auto purge interval routine will be checked on every set.
• (get|set)_auto_purge_on_get( ) — if this property is true, then the auto purge interval routine will be checked on every get.

---

👀 SEE ALSO 👀

• CHI - the successor to Cache::Cache
• Cache::Object, Cache::MemoryCache, Cache::FileCache, Cache::SharedMemoryCache, and Cache::SizeAwareFileCache

---

🫶 AUTHOR 🫶

• original author: DeWitt Clinton <dewitt@unto.net>
• last author: $Author: dclinton $
• copyright (C) 2001-2003 DeWitt Clinton

---

and that's the whole page, bestie!! 🎉 this was Cache::Cache(3pm), rendered up all pretty from perl v5.34.0, dated 2022-06-30. go forth and cache responsibly. mwah. 💖✨🎀🦋