CHI(3pm)

📦
version 0.61 · 4 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

CHI — Unified cache handling interface. yep, that's the whole vibe: one API to rule all your caching 💖 (it lives in the User Contributed Perl Documentation corner of the man pages, btw)

✨ VERSION ✨

version 0.61 — the one you're reading rn 🎀

🦋 SYNOPSIS 🦋

okay so here's the whole thing in one look, bestie:

use CHI;

# Choose a standard driver
#
my $cache = CHI->new( driver => 'Memory', global => 1 );
my $cache = CHI->new( driver => 'RawMemory', global => 1 );
my $cache = CHI->new( driver => 'File',
    root_dir => '/path/to/root'
);
my $cache = CHI->new( driver => 'FastMmap',
    root_dir   => '/path/to/root',
    cache_size => '1k'
);
my $cache = CHI->new( driver  => 'Memcached::libmemcached',
    servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
    l1_cache => { driver => 'FastMmap', root_dir => '/path/to/root' }
);
my $cache = CHI->new( driver => 'DBI',
    dbh => $dbh
);
my $cache = CHI->new( driver => 'BerkeleyDB',
    root_dir => '/path/to/root'
);

# Create your own driver
#
my $cache = CHI->new( driver => '+My::Special::Driver', ... );

# Cache operations
#
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)
});
$cache->remove($name);

like. it's giving chef's kiss simplicity, fr fr 💅

💜 DESCRIPTION 💜

so CHI is a unified caching API, and its whole purpose in life is helping you persist data for a specified period of time. that's it. that's the dream 🫶

the CHI interface gets implemented by driver classes that handle fetching, storing, and clearing data. driver classes exist — or will exist — for pretty much the entire gamut of storage backends available to Perl: memory, plain files, memory mapped files, memcached, and DBI. the whole buffet 🍓

CHI is intended as an evolution of DeWitt Clinton's Cache::Cache package. it adheres to the basic Cache API but adds new features and addresses limitations in the Cache::Cache implementation. glow-up behavior, honestly 👑

🔥 FEATURES 🔥

  • Easy to create new drivers ✨
  • Uniform support for namespaces 🎀
  • Automatic serialization of keys and values 💖
  • Multilevel caches 🦋
  • Probabilistic expiration and busy locks, to reduce cache miss stampedes 🌈
  • Optional logging and statistics collection of cache activity 📊

👑 CONSTRUCTOR 👑

to create a new cache object, call CHI->new. it takes the common options listed below. driver is required; all others are optional. no pressure or anything 😌

some drivers will take additional constructor options. for example, the File driver takes root_dir and depth options.

you can configure default options for each new cache object created — see "SUBCLASSING AND CONFIGURING CHI".

not me reminding you: CHI->new returns an instance of a subclass of CHI::Driver, not CHI. like, it's not literally a CHI object, it's the driver child. don't get confused bestie 😭
  • compress_threshold [INT] — a value in bytes. automatically compress values larger than this before storing. requires Compress::Zlib to be installed. defaults to undef, meaning no automatic compression. inspired by the parameter of the same name in Cache::Memcached.
# Compress values larger than 1MB
compress_threshold => 1024*1024
  • driver [STRING] — Required. the name of a cache driver, for example "Memory" or "File". CHI will prefix the string with "CHI::Driver::", unless it begins with '+'. e.g.
driver => 'File';                   # uses CHI::Driver::File
driver => '+My::CHI::Driver::File'  # uses My::CHI::Driver::File
  • expires_in [DURATION], expires_at [INT], expires_variance [FLOAT] — provide default values for the corresponding "set" options.
  • expires_on_backend [NUM] — if set to 0 (the default), CHI alone is aware of the expiration time and does not pass it along to the backend driver. this allows you to use "get_object" to retrieve expired items.

if set to 1, pass expiration times to backend driver if the driver supports it — for example, CHI::Driver::Memcached and CHI::Driver::CacheCache. this may allow the driver to better manage its space and evict items. note that only simple expiration time will be passed along, e.g. not "expires_variance".

if set to a number greater than 1 (e.g. 1.25), the time until expiration will be multiplied by that number before being passed to the backend driver. this gives you a customizable window of opportunity to retrieve expired items. cute, right? 🎀

  • key_digester [STRING|HASHREF|OBJECT] — digest algorithm to use on keys longer than "max_key_length" — e.g. "MD5", "SHA-1", or "SHA-256".

can be a Digest object, or a string or hashref which will passed to Digest->new(). you will need to ensure Digest is installed to use these options.

default is "MD5".

  • key_serializer [STRING|HASHREF|OBJECT] — an object to use for serializing keys that are references. see "serializer" above for the different ways this can be passed in. the default is to use the JSON backend in canonical mode (sorted hash keys).
  • label [STRING] — a label for the cache as a whole, independent of namespace — e.g. "web-file-cache". used when referring to the cache in logs, statistics, and error messages. by default, set to "short_driver_name".
  • l1_cache [HASHREF] — add an L1 cache as a subcache. see "SUBCACHES".
  • max_key_length [INT] — keys over this size will be digested. the default is driver-specific; CHI::Driver::File, for example, defaults this to 240 due to file system limits. for most drivers there is no maximum. so like, go off 🦋
  • mirror_cache [HASHREF] — add an mirror cache as a subcache. see "SUBCACHES".
  • namespace [STRING] — identifies a namespace that all cache entries for this object will be in. this allows easy separation of multiple, distinct caches without worrying about key collision. honestly iconic ✨

suggestions for easy namespace selection:

  • in a class, use the class name:
my $cache = CHI->new(namespace => __PACKAGE__, ...);
  • in a script, use the script's absolute path name:
use Cwd qw(realpath);
my $cache = CHI->new(namespace => realpath($0), ...);
  • in a web template, use the template name. for example, in Mason, $m->cache will set the namespace to the current component path.

defaults to 'Default' if not specified.

  • on_get_error [STRING|CODEREF]
  • on_set_error [STRING|CODEREF] — how to handle runtime errors occurring during cache gets and cache sets, which may or may not be considered fatal in your application. options are:
    • log (the default) — log an error, or ignore if no logger is set — see "LOGGING"
    • ignore — do nothing
    • warn — call warn() with an appropriate message
    • die — call die() with an appropriate message
    • coderef — call this code reference with three arguments: an appropriate message, the key, and the original raw error message
  • serializer [STRING|HASHREF|OBJECT] — an object to use for serializing data before storing it in the cache, and deserializing data after retrieving it from the cache. only references will be serialized; plain scalars will be placed in the cache as-is.

if this is a string, a Data::Serializer object will be created, with the string passed as the 'serializer' option and raw=1. common options include 'Storable', 'Data::Dumper', and 'YAML'. if this is a hashref, Data::Serializer->new will be called with the hash. you will need to ensure Data::Serializer is installed to use these options.

otherwise, this must be a Data::Serializer object or another object that implements serialize() and deserialize().

e.g.

# Serialize using raw Data::Dumper
my $cache = CHI->new(serializer => 'Data::Dumper');

# Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex-encoded
my $cache = CHI->new(serializer => { serializer => 'Data::Dumper', compress => 1 });

# Serialize using custom object
my $cache = CHI->new(serializer => My::Custom::Serializer->new())

the default is to use raw Storable.

  • traits [LISTREF] — list of one or more roles to apply to the "CHI::Driver" class that is constructed. the roles will automatically be prefixed with "CHI::Driver::Role::" unless preceded with a '+'. e.g.
traits => ['StoresAccessedAt', '+My::CHI::Driver::Role']

💅 INSTANCE METHODS 💅

the following methods can be called on any cache handle returned from CHI->new(). they are implemented in the CHI::Driver package. periodt. 💖

🌈 Getting and setting 🌈

get( $key, [option => value, ...] )

returns the data associated with $key. if $key does not exist or has expired, returns undef. expired items are not automatically removed and may be examined with "get_object" or "get_expires_at". they just hang out there, lurking 😭

$key may be followed by one or more name/value parameters:

  • expire_if [CODEREF] — if $key exists and has not expired, call code reference with the CHI::CacheObject and CHI::Driver as the parameters. if code returns a true value, "get" returns undef as if the item were expired. for example, to treat the cache as expired if $file has changed since the value was computed:
$cache->get('foo', expire_if => sub { $_[0]->created_at < (stat($file))[9] });
  • busy_lock [DURATION] — if the value has expired, the get will still return undef, but the expiration time of the cache entry will be set to the current time plus the specified duration. this is used to prevent multiple processes from recomputing the same expensive value simultaneously. the problem with this technique is that it doubles the number of writes performed — see "expires_variance" for another technique.
  • obj_ref [SCALARREF] — if the item exists in cache (even if expired), place the CHI::CacheObject object in the provided SCALARREF.

set( $key, $data, [$expires_in | "now" | "never" | options] )

associates $data with $key in the cache, overwriting any existing entry. returns $data. 💖

the third argument to "set" is optional, and may be either a scalar or a hash reference. if it is a scalar, it may be the string "now", the string "never", or else a duration treated as an expires_in value described below. if it is a hash reference, it may contain one or more of the following options. most of these options can be provided with defaults in the cache constructor.

okay so that's where we pause bestie, the options themselves are coming up next 🎀

  • expires_in [DURATION] — how long from right now until this data expires. DURATION can be a plain integer number of seconds, or a whole duration expression if you're feeling fancy. ⏳
  • expires_at [INT] — the epoch time at which the data expires. Like, the actual timestamp, bestie. 🕰️
  • expires_variance [FLOAT] — okay so this one is so cool. It controls the variable expiration feature, which lets items expire a little earlier than the stated expiration time, to help prevent cache miss stampedes. (Yes, stampedes. In your cache. 🦬)

Value goes between 0.0 and 1.0. 0.0 means items expire exactly when specified — feature is disabled, periodt. 1.0 means items might expire anytime from now until the stated expiration time. The default is 0.0. A setting of 0.10 to 0.25 would introduce a small amount of variation without interfering too much with intended expiration times. ✨

The probability of expiration increases as a function of how far along we are in the potential expiration window, with the probability being near 0 at the beginning of the window and approaching 1 at the end.

For example, in all of the following cases, an item might be considered expired any time between 15 and 20 minutes, with about a 20% chance at 16 minutes, a 40% chance at 17 minutes, and a 100% chance at 20 minutes. 🔥

my $cache = CHI->new ( ..., expires_variance => 0.25, ... );
$cache->set($key, $value, '20 min');
$cache->set($key, $value, { expires_at => time() + 20*60 });

my $cache = CHI->new ( ... );
$cache->set($key, $value, { expires_in => '20 min', expires_variance => 0.25 });

CHI will make a new probabilistic choice every time it needs to know whether an item has expired (i.e. it does not save the results of its determination), so you can get situations like this:

my $value = $cache->get($key);     # returns undef (indicating expired)
my $value = $cache->get($key);     # returns valid value this time!

if ($cache->is_valid($key))        # returns undef (indicating expired)
if ($cache->is_valid($key))        # returns true this time!

Typical applications won't be affected by this, since the object is recomputed as soon as it is determined to be expired. But it's something to be aware of. 👀

🧮 compute( $key, $options, $code )

Combines the get and set operations in a single call. It attempts to get $key; if that's successful, it returns the value. Otherwise it calls $code and uses the return value as the new value for $key, which is then returned. Caller context (scalar or list) is respected. 💅

$options can be undef, a scalar, or a hash reference. If it is undef, it has no effect. If it is a scalar, it is treated as the expires_in duration and passed as the third argument to set. If it is a hash reference, it may contain name/value pairs for both get and set. e.g.

# No expiration
my $value = $cache->compute($key, undef, sub {
    # compute and return value for $key here
});

# Expire in 5 minutes
my $value = $cache->compute($key, '5min', sub {
    # compute and return value for $key here
});

# Expire in 5 minutes or when a particular condition occurs
my $value = $cache->compute($key,
    { expires_in => '5min', expire_if => sub { ... } },
    sub {
       # compute and return value for $key here
});

# List context
my @value = $cache->compute($key, '5min', sub {
    ...
    return @some_list;
});

This method will eventually support the ability to recompute a value in the background just before it actually expires, so that users are not impacted by recompute time. 🔮

Note: Prior to version 0.40, the last two arguments were in reverse order; both will be accepted for backward compatibility. We think the coderef looks better at the end. 🙈

🗑️ Removing and expiring

remove( $key )

Remove the data associated with the $key from the cache. Bye bestie. 👋

expire( $key )

If $key exists, expire it by setting its expiration time into the past. Does not necessarily remove the data. Since this involves essentially setting the value again, remove may be more efficient for some drivers. 💀

🔍 Inspecting keys

is_valid( $key )

Returns a boolean indicating whether $key exists in the cache and has not expired. Note: expiration may be determined probabilistically if expires_variance was used. ✅

exists_and_is_expired( $key )

Returns a boolean indicating whether $key exists in the cache and has expired. Note: expiration may be determined probabilistically if expires_variance was used. 🫠

get_expires_at( $key )

Returns the epoch time at which $key definitively expires. Returns undef if the key does not exist or it has no expiration time. ⏰

get_object( $key )

Returns a CHI::CacheObject object containing data about the entry associated with $key, or undef if no such key exists. The object will be returned even if the entry has expired, as long as it has not been removed. 👑

⚛️ Atomic operations (ALPHA)

These methods combine both reading and writing of a cache entry in a single operation. The names and behaviors were adapted from memcached http://memcached.org/. 🧬

Some drivers (e.g. CHI::Driver::Memcached::libmemcached, CHI::Driver::DBI) may implement these as truly atomic operations, and will be documented thusly. The default implementations are not atomic: the get and set occur discretely and another process could potentially modify the cache in between them. 😭

These operations are labeled ALPHA because we haven't yet figured out how they integrate with other CHI features, in particular SUBCACHES. APIs and behavior may change. ⚠️

add( $key, $data, [$expires_in | "now" | "never" | options] )

Do a set, but only if $key is not valid in the cache. ➕

replace( $key, $data, [$expires_in | "now" | "never" | options] )

Do a set, but only if $key is valid in the cache. 🔁

append( $key, $new_data)

Append $new_data to whatever value is currently associated with $key. Has no effect if $key does not exist in the cache. 🤝

Returns true if $key was in the cache, false otherwise.

This is intended for simple string values only. For efficiency's sake, CHI won't attempt to check for, or handle, the case where data is serialized or compressed; the new data will simply be appended, and an error will most probably occur when you try to retrieve the value. 🚨

Does not modify expiration or other metadata. If $key exists but is expired, it will remain expired. 🥀

If you use a driver with the non-atomic (default) implementation, some appends may be lost due to race conditions. 💀

🗂️ Namespace operations

clear( )

Remove all entries from the namespace. Poof. ✨

get_keys( )

Returns a list of keys in the namespace. This may or may not include expired keys, depending on the driver. 🎀

The keys may not look the same as they did when passed into set; they may have been serialized, utf8 encoded, and/or digested (see KEY AND VALUE TRANSFORMATIONS). However, they may still be passed back into get, set, etc. to access the same underlying objects. i.e. the following code is guaranteed to produce all key/value pairs from the cache:

map { ($_, $c->get($_)) } $c->get_keys()

purge( )

Remove all entries that have expired from the namespace associated with this cache instance.

Warning: May be very inefficient, depending on the number of keys and the driver. 🐌

get_namespaces( )

Returns a list of namespaces associated with the cache. This may or may not include empty namespaces, depending on the driver. 🌸

🧺 Multiple key/value operations

The methods in this section process multiple keys and/or values at once. By default these are implemented with the obvious map operations, but some cache drivers (e.g. Cache::Memcached) can override them with more efficient implementations. 💨

get_multi_arrayref( $keys )

Get the keys in list reference $keys, and return a list reference of the same length with corresponding values or undefs. 📋

get_multi_hashref( $keys )

Like get_multi_arrayref, but returns a hash reference with each key in $keys mapping to its corresponding value or undef. Will only work with scalar keys. 🗺️

set_multi( $key_values, $set_options )

Set the multiple keys and values provided in hash reference $key_values. $set_options is a scalar or hash reference, used as the third argument to set. Will only work with scalar keys. 📦

remove_multi( $keys )

Removes the keys in list reference $keys. 🧹

dump_as_hash( )

Returns a hash reference containing all the non-expired keys and values in the cache. 🎁

🔧 Property accessors

chi_root_class( )

Returns the name of the root class under which this object was created, e.g. "CHI" or "My::CHI". See SUBCLASSING AND CONFIGURING CHI. 🌳

driver_class( )

Returns the full name of the driver class. e.g.

CHI->new(driver=>'File')->driver_class
   => CHI::Driver::File
CHI->new(driver=>'+CHI::Driver::File')->driver_class
   => CHI::Driver::File
CHI->new(driver=>'+My::Driver::File')->driver_class
   => My::Driver::File

You should use this rather than ref(). Due to some subclassing tricks CHI employs, the actual class of the object is neither guaranteed nor likely to be the driver class. 🎭

short_driver_name( )

Returns the name of the driver class, minus the CHI::Driver:: prefix, if any. e.g.

CHI->new(driver=>'File')->short_driver_name
   => File
CHI->new(driver_class=>'CHI::Driver::File')->short_driver_name
   => File
CHI->new(driver_class=>'My::Driver::File')->short_driver_name
   => My::Driver::File

Standard read-write accessors

expires_in
expires_at
expires_variance
label
on_get_error
on_set_error

Standard read-only accessors

namespace
serializer

🚫 Deprecated methods

The following methods are deprecated and will be removed in a later version:

is_empty

✨ DURATION EXPRESSIONS ✨

Okay so bestie, anywhere you see a duration expression — they show up in the "set" command and in a bunch of other spots around the API — it's Time::Duration::Parse doing the parsing, no cap. A duration is either:

  • just a plain number, which CHI treats like a number of seconds, or
  • a number plus a string that says the time unit.

And the unit strings it vibes with are literally these:

s second seconds sec secs
m minute minutes min mins
h hr hour hours
d day days
w week weeks
M month months
y year years

So like, all of these are valid duration expressions, fr fr:

25
3s
5 seconds
1 minute and ten seconds
1 hour

🌈 KEY AND VALUE TRANSFORMATIONS 🌈

CHI is out here with main character energy trying to accept literally any keys and values you throw at it for caching, even when the underlying driver is like "ma'am, I have limitations". 💅

🔑 Key transformations

  • Keys that are references get serialized — peep "key_serializer".
  • Keys with wide (>255) characters get utf8 encoded. 🦋
  • Keys that are longer than the underlying driver can handle get digested — see "max_key_length" and "key_digester".
  • For some drivers (hi CHI::Driver::File 👋), keys with special characters or whitespace get escaped with URL-like escaping.
Note: all the transformations up there, except for escaping, are one-way — meaning CHI doesn't try to undo them when you get stuff back from "get_keys". And they're idempotent too — meaning if you apply them a second time, nothing happens. So when you call "get_keys", the key you get back might not be exactly the one you passed in, but bestie you will be able to pass that key in and get the corresponding object. Periodt. 💖

🎀 Value transformations

  • Values that are references get automatically serialized before storing, and deserialized after retrieving — see "serializer".
  • Values with their utf8 flag turned on get utf8 encoded before storing, and utf8 decoded after retrieving.

🦋 SUBCACHES 🦋

So a cache can totally have one or more subcaches, and rn there are two types: L1 and mirror.

💜 L1 cache

An L1 (or "level one") cache sits in front of the primary cache, usually so the stuff you hit all the time loads faster. Like, this here puts an in-process Memory cache in front of a Memcached cache:

my $cache = CHI->new(
    driver   => 'Memcached',
    servers  => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
    l1_cache => { driver => 'Memory', global => 1, max_size => 1024*1024 }
);

On a "get", the L1 cache gets checked first — if there's a valid value in there, it's returned, done. If not, the primary cache gets checked — and if that has a valid value, it's returned, and the value gets dropped into the L1 cache with the same expiration time. So basically, the items fetched most often from the primary cache will tend to end up chillin' in the L1 cache. Iconic behavior tbh. ✨

"set" operations get distributed to both the primary and the L1 cache.

You can reach the L1 cache with the "l1_cache" method. Like, this clears the L1 cache but leaves the primary cache intact:

$cache->l1_cache->clear();

🪞 Mirror cache

A mirror cache is a write-only cache that, over time, mirrors the content of the primary cache. "set" operations get distributed to both the primary and the mirror cache, but "get" operations only ever go to the primary cache. No cap.

Mirror caches are the moment when you wanna migrate from one cache to another. 🌈 You populate a mirror cache, then switch over to it once it's populated enough. For example, here we're migrating from an old cache directory to a new one:

my $cache = CHI->new(
    driver          => 'File',
    root_dir        => '/old/cache/root',
    mirror_cache => { driver => 'File', root_dir => '/new/cache/root' },
);

We let that run for a few hours (or however long it needs), then swap it out for:

my $cache = CHI->new(
    driver   => 'File',
    root_dir => '/new/cache/root'
);

You can reach the mirror cache with the "mirror_cache" method. Like, to see how many keys have made it over to the mirror cache:

my @keys = $cache->mirror_cache->get_keys();

🌸 Creating subcaches

Like the examples above show, you make subcaches by passing the "l1_cache" and/or "mirror_cache" option to the CHI constructor. Those options should contain a hash of options for creating the subcache with.

The cache that contains the subcache is called the parent cache.

These options get automatically inherited by the subcache from the parent cache, and you may not override them:

expires_at
expires_in
expires_variance
serializer

(Reason: for efficiency, we wanna create a single cache object and store it in both caches. The cache object holds expiration info and it's dependent on the serializer. At some point we could conceivably add code that uses a single object or separate objects as needed, and then we'd let the above be overridden. But not today. 🙈)

These options also get automatically inherited by the subcache from the parent cache, but you may override them:

namespace
on_get_error
on_set_error

Every other option gets initialized in the subcache like normal, no matter what its value is in the parent.

Also just so you know: it's not currently possible to pass an existing cache in as a subcache. 💀

🧚 Common subcache behaviors

These behaviors hold no matter what type of subcache it is.

These methods get distributed to both the primary cache and the subcache:

clear
expire
purge
remove

These methods return info solely from the primary cache. That said, you're free to call them explicitly on the subcache. (Trying to automatically merge in subcache info would require way too much guessing about what the caller actually wants, and we are not doing that.)

get_keys
get_namespaces
get_object
get_expires_at
exists_and_is_expired
is_valid
dump_as_hash

👑 Multiple subcaches

It is valid for a cache to have one of each kind of subcache — like an L1 cache and a mirror cache, bestie.

A cache can't have more than one of each kind of subcache, but a subcache can have its own subcaches, and so on and so on. Like:

my $cache = CHI->new(
    driver   => 'Memcached',
    servers  => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
    l1_cache => {
        driver     => 'File',
        root_dir   => '/path/to/root',
        l1_cache   => { driver => 'RawMemory', global => 1 }
    }
);

💖 Methods for parent caches

has_subcaches( )

Returns a boolean saying whether this cache has subcaches.

l1_cache( )

Returns the L1 cache for this cache, if it has one. Can only be called if has_subcaches is true.

mirror_cache( )

Returns the mirror cache for this cache, if it has one. Can only be called if has_subcaches is true.

subcaches( )

Returns the subcaches for this cache, in arbitrary order. Can only be called if has_subcaches is true.

🎀 Methods for subcaches

is_subcache( )

Returns a boolean saying whether this is a subcache.

subcache_type( )

Returns the type of subcache as a string, e.g. 'l1_cache' or 'mirror_cache'. Can only be called if is_subcache is true.

parent_cache( )

Returns the parent cache (weakened to prevent circular reference). Can only be called if is_subcache is true.

⭐ Developing new kinds of subcaches

As of right now, subcache behavior is hardcoded into CHI::Driver, so there's no easy way to modify how existing subcache types behave or to create brand new ones. We'd love to make this more flexible eventually, bestie. Someday. 🫶

💅 SIZE AWARENESS 💅

If "is_size_aware" or "max_size" get passed to the constructor, the cache becomes size aware — meaning it keeps track of its own size (in bytes) as items get added and removed. You can grab a cache's size with "get_size".

Size aware caches generally keep track of their size in a separate meta-key, and they have to do an extra store every time the size changes (like on every set and remove). It's giving ✨diligent✨.

🔥 Maximum size and discard policies

If a cache's size rises above its "max_size", items get discarded until the cache size is sufficiently below the max size. (Peep "max_size_reduction_factor" for how to fine-tune that.)

The order items get discarded in is controlled by "discard_policy". The default discard policy is 'arbitrary', which discards items in an arbitrary order. The available policies and the default policy can differ with each driver — like, the CHI::Driver::Memory driver provides and defaults to an 'LRU' policy.

🌈 Appropriate drivers

Size awareness was chiefly designed for, and works well with, the CHI::Driver::Memory driver: you often need to enforce a maximum size on a memory cache, and the overhead of tracking size in memory is negligible. That said, the capability may be useful with other drivers too.

Some drivers — for example, CHI::Driver::FastMmap and CHI::Driver::Memcached — inherently keep track of their size and enforce a maximum size on their own, and it makes no sense to turn on CHI's size awareness for those.

Also heads up: for drivers that can't atomically read and update a value — for example, CHI::Driver::File — there's a race condition in the updating of size that can cause the size to grow inaccurate over time. So like, be aware, bestie. 💀

💖 SUBCLASSING AND CONFIGURING CHI 💖

okay bestie, so you can literally make your own lil baby CHI subclass for your app and configure it however you want — like, predefine storage types and defaults for all your new cache objects. and the best part? your config is fully independent from the main CHI class and from everybody else's CHI subclasses. no crossover, no drama. 🫶

start with a super trivial subclass:

package My::CHI;

use base qw(CHI);
1;

then you just... use your subclass wherever you'd use CHI:

my $cache = My::CHI->new( ... );

print $cache->chi_root_class;
   ==> 'My::CHI'

ngl this changes literally nothing by itself. but here's one with actual config in it:

package My::CHI;

use base qw(CHI);

__PACKAGE__->config({
    storage   => {
        local_file => { driver => 'File', root_dir => '/my/root' },
        memcached  => {
            driver  => 'Memcached::libmemcached',
            servers => [ '10.0.0.15:11211', '10.0.0.15:11212' ]
        },
    },
    namespace => {
        'Foo' => { storage => 'local_file' },
        'Bar' => { storage => 'local_file', depth => 3 },
        'Baz' => { storage => 'memcached' },
    }
    defaults  => { storage => 'local_file' },
    memoize_cache_objects => 1,
});

1;

each one of those config keys gets its own moment in the spotlight in the next section 👑

✨ Configuration keys ✨

  • storage — a map of names → parameter hashrefs. it's basically a way to bundle up common sets of parameters you'd otherwise be retyping all over the place. so if you define
storage => {
    local_file => { driver => 'File', root_dir => '/my/root' },
    ...
}

then

my $cache = My::CHI->new
   (namespace => 'Foo', storage => 'local_file');

is equivalent to

my $cache = My::CHI->new
   (namespace => 'Foo', driver => 'File', root_dir => '/my/root');
  • namespace — a map of namespace names → parameter hashrefs. when you create a cache object with that namespace, the hashref of parameters gets applied as defaults. like, if you define
namespace => {
    'Foo' => { driver => 'File', root_dir => '/my/root' },
    'Bar' => { storage => 'database' },
    ...
}

then

my $cache1 = My::CHI->new
   (namespace => 'Foo');
my $cache2 = My::CHI->new
   (namespace => 'Bar');

is equivalent to

my $cache1 = My::CHI->new
   (namespace => 'Foo', driver => 'File', root_dir => '/my/root');
my $cache2 = My::CHI->new
   (namespace => 'Bar', storage => 'database');
  • defaults — a hash of parameters used as core defaults for every single cache object created under this root class. e.g.
defaults => {
    on_get_error => 'die',
    expires_variance => 0.2,
}

these can get overridden by namespace defaults, storage settings, or the params you pass to new. ✨

  • memoize_cache_objects — true or false, says whether My::CHI->new should memoize and hand back the same cache object when given the same parameters. this can speed things up if you're creating cache objects constantly. heads up: it currently only works for 0- or 1-key parameter hashes. e.g.
My::CHI->config({
    memoize_cache_objects => 1,
});

then

# $cache1 and $cache2 will be the same object, regardless of what
# namespace and storage defaults are associated with 'Foo'
#
my $cache1 = My::CHI->new(namespace => 'Foo');
my $cache2 = My::CHI->new(namespace => 'Foo');

# $cache3 and $cache4 will be different objects
#
my $cache3 = My::CHI->new
   (namespace => 'Bar', driver => 'File', root_dir => '/my/root');
my $cache4 = My::CHI->new
   (namespace => 'Bar', driver => 'File', root_dir => '/my/root');

and to clear out the memoized cache objects, you call

My::CHI->clear_memoized_cache_objects;

🌸 How defaults are combined 🌸

defaults get applied in this order, highest to lowest precedence:

  1. parameters passed in new
  2. namespace defaults, if any
  3. storage settings, if any
  4. core defaults defined under defaults

like, the most specific thing wins, periodt. 💅

🦋 Inheritance of config 🦋

a subclass will automatically inherit its parent's configuration if it doesn't call config itself (ala Class::Data::Inheritable). free config, no cap. 🎀

🍓 Reading config from a file 🍓

use YAML::XS qw(LoadFile);

__PACKAGE__->config(LoadFile("/path/to/cache.yml"));

look at that, config straight outta a file. iconic.

🌈 AVAILABILITY OF DRIVERS 🌈

these drivers are currently available as part of this distribution:

  • CHI::Driver::Memory — in-process memory based cache
  • CHI::Driver::RawMemory — in-process memory based cache that stores references directly instead of serializing/deep-copying
  • CHI::Driver::File — file-based cache using one file per entry in a multi-level directory structure
  • CHI::Driver::FastMmap — shared memory interprocess cache via mmap'ed files
  • CHI::Driver::Null — dummy cache in which nothing is stored
  • CHI::Driver::CacheCache — CHI wrapper for Cache::Cache

and these drivers are currently available as separate CPAN distributions:

  • CHI::Driver::Memcached — distributed memory-based cache (works with Cache::Memcached, Cache::Memcached::Fast, and Cache::Memcached::libmemcached)
  • CHI::Driver::DBI — cache in any DBI-supported database
  • CHI::Driver::BerkeleyDB — cache in BerkeleyDB files
  • CHI::Driver::Redis — cache in Redis <http://redis.io/>
  • CHI::Driver::SharedMem — cache in shared memory

this list is likely incomplete. a complete set of drivers can be found on CPAN by searching for CHI::Driver. 🔍

🔥 PERFORMANCE COMPARISON OF DRIVERS 🔥

see CHI::Benchmarks for a comparison of read/write times of both CHI and non-CHI cache implementations.

etc/bench/bench.pl in the CHI distribution contains a script to run these types of benchmarks on your own system. go run it, bestie, see how your setup's doing. 📊

💜 DEVELOPING NEW DRIVERS 💜

see CHI::Driver::Development for information on developing new drivers. yes, you can build your own. main character energy. 👑

⭐ LOGGING ⭐

CHI uses Log::Any for logging events. for example, a debug log message is sent with category CHI::Driver for every cache get and set. like, every single one. 👀

see Log::Any documentation for how to control where logs get sent, if anywhere.

💀 STATS 💀

CHI can record statistics — number of hits, misses and sets — on a per-namespace basis and log the results to your Log::Any logger. then you can use the utilities included with this distribution to read stats back from the logs and report a summary. see CHI::Stats for details. 📈

💞 RELATION TO OTHER MODULES 💞

ok bestie, let's do the family tree moment, because CHI did NOT appear out of nowhere. She has ancestors, and we're gonna give them their flowers. 🌸

🗂️ Cache::Cache

CHI is literally intended as an evolution of DeWitt Clinton's Cache::Cache package. She starts with the same basic API (which has proven durable over time, so respect) but fixes some implementation shortcomings that just cannot be fixed in Cache::Cache because of backward compatibility concerns. Like, they're stuck, and we're not. 💅

In particular:

  • Performance — Some of Cache::Cache's subclasses (e.g. Cache::FileCache) have been justifiably criticized as inefficient. CHI was designed from the ground up with performance in mind, both in terms of general overhead and in the built-in driver classes. Method calls are kept to a minimum, data is only serialized when necessary, and metadata such as expiration time is stored in packed binary format alongside the data. it's giving efficient. 🔥
  • Ease of subclassing — New Cache::Cache subclasses can be tedious to create, because of a lack of code refactoring, the use of non-OO package subroutines, and the separation of "cache" and "backend" classes. With CHI, the goal is to make creating new drivers as easy as possible — roughly the same as writing a TIE interface to your data store. Concerns like serialization and expiration options are handled by the driver base class so individual drivers don't have to worry about them. main character base class energy ✨
  • Increased compatibility with cache implementations — Probably because of the reasons above, Cache::Cache subclasses were never created for some of the most popular caches available on CPAN, e.g. Cache::FastMmap and Cache::Memcached. CHI's goal is to be able to support these and other caches with a minimum performance overhead and minimum of glue code required. 🫶

🌀 Cache

The Cache distribution is another redesign and implementation of Cache, created by Chris Leishman in 2003. Like CHI, it improves performance and reduces the barrier to implementing new cache drivers. It breaks with the Cache::Cache interface in a few ways that I considered non-negotiable — for example, get/set do not serialize data, and namespaces are an optional feature that drivers may decide not to implement. 🎀

🍓 Cache::Memcached, Cache::FastMmap, etc.

CPAN sports a variety of full-featured standalone cache modules representing particular backends. CHI does not reinvent these — she simply wraps them with an appropriate driver. For example, CHI::Driver::Memcached and CHI::Driver::FastMmap are thin layers around Cache::Memcached and Cache::FastMmap. thin. layers. iconic. 💅

Of course, because these modules already work on their own, there will be some overlap. Cache::FastMmap, for example, already has code to serialize data and handle expiration times. Here's how CHI resolves these overlaps:

  • Serialization — CHI handles her own serialization, passing a flat binary string to the underlying cache backend. The notable exception is CHI::Driver::RawMemory which does no serialization. 🧚
  • Expiration — CHI packs expiration times (as well as other metadata) inside the binary string passed to the underlying cache backend. The backend is unaware of these values; from its point of view the item has no expiration time. Among other things, this means that you can use CHI to examine expired items (e.g. with $cache->get_object) even if this is not supported natively by the backend. obsessed with the sneak peek ability, ngl. 👑
At some point CHI will provide the option of explicitly notifying the backend of the expiration time as well. This might allow the backend to do better storage management, etc., but would prevent CHI from examining expired items. (future stuff, not here yet, don't come for me)

Naturally, using CHI's FastMmap or Memcached driver will never be as time or storage efficient as simply using Cache::FastMmap or Cache::Memcached. In terms of performance, we've attempted to make the overhead as small as possible, on the order of 5% per get or set (benchmarks coming soon). In terms of storage size, CHI adds about 16 bytes of metadata overhead to each item. How much this matters obviously depends on the typical size of items in your cache. ✨

📣 SUPPORT AND DOCUMENTATION 📣

Questions and feedback are welcome, and should be directed to the perl-cache mailing list:

http://groups.google.com/group/perl-cache-discuss

Bugs and feature requests will be tracked at RT:

http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI
bug-chi@rt.cpan.org

The latest source code can be browsed and fetched at:

http://github.com/jonswar/perl-chi/tree/master
git clone git://github.com/jonswar/perl-chi.git

🫶 ACKNOWLEDGMENTS 🫶

Thanks to Dewitt Clinton for the original Cache::Cache, to Rob Mueller for the Perl cache benchmarks, and to Perrin Harkins for the discussions that got this going. the way that this whole thing started with a conversation… 😭💖

CHI was originally designed and developed for the Digital Media group of the Hearst Corporation, a diversified media company based in New York City. Many thanks to Hearst management for agreeing to this open source release. 🗽✨

👀 SEE ALSO 👀

  • Cache::Cache

✍️ AUTHOR ✍️

Jonathan Swartz <swartz@pobox.com>

This software is copyright (c) 2021 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. 💖

ok that's the whole thing bestie, you made it to the end, congratulations you're a CHI expert now 🎓💅✨ This page is from perl v5.32.1, dated 2021-10-15, and yes it's the CHI(3pm) manpage. go forth and cache responsibly, ily 🫶🌸

📦 where this page comes from