Tie::Cache::LRU(3pm)

🌸 NAME 🌸

Tie::Cache::LRU — it's a Least-Recently Used cache, bestie. That's the whole vibe. This is the Tie::Cache::LRU(3pm) page from the User Contributed Perl Documentation, and we're gonna get you fluent in it. 💅

---

✨ SYNOPSIS ✨

use Tie::Cache::LRU;

tie %cache, 'Tie::Cache::LRU', 500;
tie %cache, 'Tie::Cache::LRU', '400k'; #UNIMPLEMENTED

# Use like a normal hash.

$cache_obj = tied %cache;
$current_size = $cache_obj->curr_size;

$max_size = $cache_obj->max_size;
$cache_obj->max_size($new_size);

no cap, that's literally the whole entry point. Tie a hash, use it like a hash, grab the object with tied when you need the fancy stuff. 🫶

---

🦋 DESCRIPTION 🦋

NOTE There are no plans to update this module. Please consider using CHI or other caching framework. (Not me being the bearer of bad news 😭 — but fr fr, that's what it says.)

Okay so here's the tea ☕: this is an implementation of a least-recently used (LRU) cache that keeps the cache in RAM.

An LRU cache is similar to the kind of cache used by a web browser. New items get placed into the top of the cache. When the cache grows past its size limit, it throws away items off the bottom. The trick — the iconic part, the main character energy — is that whenever an item is -accessed-, it gets pulled back to the top. The end result of all this is that items which are frequently accessed tend to stay in the cache. Slay. 👑

---

💖 USAGE 💖

The cache is extremely simple — it just holds a simple scalar. If you want to cache an object, just place it into the cache:

$cache{$obj->id} = $obj;

This doesn't make a copy of the object, it just holds a reference to it.

(Note: This means that your object's destructor will not be called until it has fallen out of the cache (and all other references to it have disappeared, of course!)) 💀

If you want to cache an array, place a reference to it in the cache:

$cache{$some_id} = \@array;

Or, if you're worried about the consequences of tossing around references and want to cache a copy instead, you can do something like this:

$cache{$some_id} = [@array];

---

🎀 Tied Interface 🎀

tie

tie %cache, 'Tie::Cache::LRU';
tie %cache, 'Tie::Cache::LRU', $cache_size;

This ties a cache to %cache which will hold a maximum of $cache_size keys. If $cache_size is not given it uses a default value, Tie::Cache::LRU->DEFAULT_MAX_SIZE.

If the size is set to 0, the cache is effectively turned off. This is useful for "removing" the cache from a program without having to make deep alterations to the program itself, or for checking performance differences with and without a cache. 🌈

All of the expected hash operations (exists, delete, slices, etc...) work on the %cache. Periodt. ✨

---

🧚 Object Interface 🧚

There's a few things you just can't do through the tied interface. To do them, you need to get at the underlying object, which you do with tied().

$cache_obj = tied %cache;

And then you can call a few methods on that object:

max_size

$cache_obj->max_size($size);
$size = $cache_obj->max_size;

An accessor to alter the maximum size of the cache on the fly. 🦋

If max_size() is reset, and it is lower than the current size, the cache is immediately truncated.

The size must be an integer greater than or equal to 0.

curr_size

$size = $cache_obj->curr_size;

Returns the current number of items in the cache. That's it, that's the whole method. 💜

---

💅 NOTES 💅

This is just a thin subclass of Tie::Cache::LRU::Array. iykyk. 🙈

---

⭐ TODO ⭐

• Should eventually allow the cache to be in shared memory.
• Max size by memory use unimplemented.

(yes bestie, '400k' up there in the synopsis is part of that unimplemented dream. we stay manifesting. ✨)

---

👑 COPYRIGHT AND LICENSE 👑

Copyright 1999-2015 by Michael G Schwern <schwern@pobox.com>.

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

See <http://dev.perl.org/licenses/>

---

🌸 AUTHOR 🌸

Michael G Schwern <schwern@pobox.com>.

---

🫶 SEE ALSO 🫶

• CHI for a more modern cache implementation.
• Tie::Cache::LRU::Array, Tie::Cache::LRU::LinkedList, Tie::Cache::LRU::Virtual, Tie::Cache

---

okay that's the whole page bestie, you ate that 💖 This was perl v5.36.0, dated 2022-08-29, and it's the Tie::Cache::LRU(3pm) manual from User Contributed Perl Documentation. go forth and cache responsibly, mwah 🎀✨