Cache(3pm)

📦
version 0.21 · 6 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

🦋 NAME 🦋

Tie::Cache — an LRU Cache in Memory, bestie. That's it, that's the whole personality. (You probably got here looking for Cache(3pm), and yes, you're in the right place 💖)

🌸 SYNOPSIS 🌸

okay so here's the whole vibe in code, no cap:

use Tie::Cache;
tie %cache, 'Tie::Cache', 100, { Debug => 1 };
tie %cache2, 'Tie::Cache', { MaxCount => 100, MaxBytes => 50000 };
tie %cache3, 'Tie::Cache', 100, { Debug => 1 , WriteSync => 0};

# Options ##################################################################
#
# Debug =>      0 - DEFAULT, no debugging output
#               1 - prints cache statistics upon destroying
#               2 - prints detailed debugging info
#
# MaxCount =>   Maximum entries in cache.
#
# MaxBytes =>   Maximum bytes taken in memory for cache based on approximate
#               size of total cache structure in memory
#
#               There is approximately 240 bytes used per key/value pair in the cache for
#               the cache data structures, so a cache of 5000 entries would take
#               at approximately 1.2M plus the size of the data being cached.
#
# MaxSize  =>   Maximum size of each cache entry. Larger entries are not cached.
#                   This helps prevent much of the cache being flushed when
#                   you set an exceptionally large entry.  Defaults to MaxBytes/10
#
# WriteSync =>  1 - DEFAULT, write() when data is dirtied for
#                   TRUE CACHE (see below)
#               0 - write() dirty data as late as possible, when leaving
#                   cache, or when cache is being DESTROY'd
#
############################################################################

# cache supports normal tied hash functions
$cache{1} = 2;       # STORE
print "$cache{1}\n"; # FETCH

# FIRSTKEY, NEXTKEY
while(($k, $v) = each %cache) { print "$k: $v\n"; }

delete $cache{1};    # DELETE
%cache = ();         # CLEAR

so like, breaking down those options for you because I love you 🫶

  • Debug — how loud do you want this thing to be? 0 is the DEFAULT and it says absolutely nothing. 1 prints cache statistics when the thing gets destroyed. 2 prints detailed debugging info, like it's telling you its whole life story.
  • MaxCount — the maximum number of entries allowed in the cache.
  • MaxBytes — the maximum bytes taken in memory for the cache, based on the approximate size of the total cache structure in memory.
  • 💀 real talk on the math: there's approximately 240 bytes used per key/value pair in the cache for the cache data structures, so a cache of 5000 entries would take at approximately 1.2M plus the size of the data being cached.
  • MaxSize — maximum size of each cache entry. Larger entries are not cached at all. This helps prevent much of the cache being flushed when you set an exceptionally large entry. Defaults to MaxBytes/10.
  • WriteSync — 1 is the DEFAULT: it write()s when data is dirtied for the TRUE CACHE (peep below 👇). 0 means write() dirty data as late as possible — when leaving cache, or when the cache is being DESTROY'd.

and then the tied-hash moves, because a cache that doesn't act like a hash is a scam:

  • $cache{1} = 2; — STORE
  • print "$cache{1}\n"; — FETCH
  • while(($k, $v) = each %cache) { print "$k: $v\n"; } — FIRSTKEY, NEXTKEY
  • delete $cache{1}; — DELETE
  • %cache = (); — CLEAR

✨ DESCRIPTION ✨

This module implements a least recently used (LRU) cache in memory through a tie interface. So every time you store data in the tied hash, that key/value pair gets an entry time attached to it, and as the cache fills up, the members of the cache that are the oldest get removed to make room for the new entries. It's giving natural selection but for your data 🌈

So the cache only "remembers" the last written entries, up to the size of the cache. This can be especially useful if you access great amounts of data, but only access a minority of the data a majority of the time. literally the plot of every relationship tbh.

The implementation is a hash, for quick lookups, overlaying a doubly linked list for quick insertion and deletion. On a WinNT PII 300, writes to the hash were done at a rate 3100 per second, and reads from the hash at 6300 per second. Work has been done to optimize refreshing cache entries that are frequently read from — code like $cache{entry}, which moves the entry to the end of the linked list internally. she's efficient AND pretty, we love a main character 👑

🎀 INSTALLATION 🎀

Tie::Cache installs easily using the make or nmake commands as shown below. Otherwise, just copy Cache.pm to $PERLLIB/site/Tie

> perl Makefile.PL
> make
> make test
> make install
  • * use nmake for win32
  • ** you can also just copy Cache.pm to $perllib/Tie

🏆 BENCMARKS 🏆

(okay the section is literally spelled "BENCMARKS", I'm just the messenger, don't @ me 💅)

There is another simpler LRU cache implementation in CPAN, Tie::Cache::LRU, which has the same basic size limiting functionality, and for this functionality, the exact same interface. twin behavior, honestly.

Through healthy competition, Michael G Schwern got Tie::Cache::LRU mostly faster than Tie::Cache on reads & writes:

Cache Size 5000       Tie::Cache 0.17  Tie::Cache::LRU 20110205.00
10000 Writes             0.63 CPU sec          0.47 CPU sec
40000 Reads              0.79 CPU sec          0.71 CPU sec
10000 Deletes            0.23 CPU sec          0.26 CPU sec

Unless you are using TRUE CACHE or MaxBytes functionality, using Tie::Cache::LRU could be an easy replacement for Tie::Cache.

OTOH one nice thing about this module is its lack of external module dependencies! zero baggage, no third-party drama, just vibes 💜

💖 TRUE CACHE 💖

To use class as a true cache, which acts as the sole interface for some data set, subclass the real cache off Tie::Cache, with @ISA = qw( 'Tie::Cache' ) notation. Then override the read() method for behavior when there is a cache miss, and the write() method for behavior when the cache's data changes.

When WriteSync is 1 or TRUE (DEFAULT), write() is called immediately when data in the cache is modified. If set to 0, data that has been modified in the cache gets written out when the entries are deleted or during the DESTROY phase of the cache object, usually at the end of a script.

To have the dirty data write() periodically while WriteSync is set to 0, there is a flush() cache API call that will flush the dirty writes in this way. Just call the flush() API like:

my $write_flush_count = tied(%cache)->flush();

The flush() API was added in the .17 release thanks to Rob Bloodgood. shoutout king 🫡

🧚 TRUE CACHE EXAMPLE 🧚

here's a whole working example, character for character, no edits, slay:

use Tie::Cache;

# personalize the Tie::Cache object, by inheriting from it
package My::Cache;
@ISA = qw(Tie::Cache);

# override the read() and write() member functions
# these tell the cache what to do with a cache miss or flush
sub read {
   my($self, $key) = @_;
   print "cache miss for $key, read() data\n";
   rand() * $key;
}
sub write {
   my($self, $key, $value) = @_;
   print "flushing [$key, $value] from cache, write() data\n";
}

my $cache_size   = $ARGV[0] || 2;
my $num_to_cache = $ARGV[1] || 4;
my $Debug = $ARGV[2] || 1;

tie %cache, 'My::Cache', $cache_size, {Debug => $Debug};

# load the cache with new data, each through its contents,
# and then reload in reverse order.
for(1..$num_to_cache) { print "read data $_: $cache{$_}\n" }
while(my($k, $v) = each %cache) { print "each data $k: $v\n"; }
for(my $i=$num_to_cache; $i>0; $i--) { print "read data $i: $cache{$i}\n"; }

# flush writes now, trivial use since will happen in DESTROY() anyway
tied(%cache)->flush();

# clear cache in 2 ways, write will flush out to disk
%cache = ();
undef %cache;

🌟 NOTES 🌟

Many thanks to all those who helped make this module a reality, including:

  • :) Tom Hukins who provided me insight and motivation for finishing this module.
  • :) Jamie McCarthy, for trying to make Tie::Cache be all that it can be.
  • :) Rob Fugina who knows how to "TRULY CACHE".
  • :) Rob Bloodgood, for the TRUE CACHE flush() API

we stan a supportive community 😭💖

🫶 AUTHOR 🫶

Please send any questions or comments to Joshua Chamas at chamas@alumni.stanford.org

Copyright (c) 1999-2012 Joshua Chamas, Chamas Enterprises Inc. Sponsored by development on NodeWorks http://nodeworks.com and Web Test.org http://web-test.org

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the page bestie 💅 this was perl v5.36.0, dated 2022-10-22, filed under Cache(3pm) — go forth and cache responsibly, ily 🦋✨

📦 where this page comes from