Cache::Entry(3pm)

💖 Cache::Entry ✨

okay so bestie, welcome to Cache::Entry(3pm) — that's the User Contributed Perl Documentation one, and it's literally the interface for a cache entry 🎀. Sit down, grab a strawberry, we're doing this.

---

🌸 NAME 🌸

Cache::Entry — the interface for a cache entry. that's it, that's the name, short and iconic 👑

---

🦋 SYNOPSIS 🦋

my Cache::Entry $entry = $cache->entry( $key )
my $data;
if ($entry->exists()) {
    $data = $entry->get();
}
else {
    $data = get_some_data($key);
    $entry->set($data, '10 minutes');
}

look at that flow. check if it exists, grab it if it does, otherwise go get the data and set it with a lil expiry. chef's kiss, no notes 💅

---

✨ DESCRIPTION ✨

so. objects derived from Cache::Entry represent an entry in a Cache. the methods are all about acting on the data in that entry, and letting you set stuff like the expiry time. very main character, very "I hold your data and I know when it dies" 💀

important bestie!! you should NOT create instances of Cache::Entry directly. do not do it. instead, use the entry($key) method of a Cache instance. that's the way. periodt.

---

💅 METHODS 💅

• my $cache = $e->cache() — hands you back a reference to the cache object this entry came from. it's giving "who's your parent" 🫶
• my $key = $e->key() — returns the cache key this entry is associated with. its little name tag 🏷️
• my $bool = $e->exists() — returns a boolean value (1 or 0) telling you whether there's any data present in the cache for this entry. yes or no, no in-between ✨
• $e->set( $data, [ $expiry ] ) — stores the data into the cache. the data must be a scalar (if you wanna store more complex data types, go look at freeze and thaw below, i got you). the expiry time can be passed as an optional 2nd argument, and it's in the same form as for 'set_expiry($time)'.
• my $data = $e->get() — returns the data from the cache, or undef if the entry doesn't exist. if it's not there, it's just not there, don't take it personally 😭
• my $size = $e->size() — returns the size of the entry data, or undef if the entry doesn't exist. measuring the fit 📏
• $e->remove() — clears the data for this entry from the cache. bye bye data, you were loved 🧚
• my $expiry = $e->expiry() — returns the expiry time of the entry, in seconds since the epoch. ticking clock energy ⏰
• $e->set_expiry( $time ) — sets the expiry time in seconds since the epoch, or you can use a string like '10 minutes'. valid units are s, second, seconds, sec, m, minute, minutes, min, h, hour, hours, w, week, weeks, M, month, months, y, year and years. (yes bestie, lowercase m is minutes and uppercase M is months — read it twice, i know 💀) you can also specify an absolute time, such as '16 Nov 94 22:28:20' or any other time that Date::Parse can understand. and finally, the strings 'now' and 'never' may also be used. 'never' is such a mood ngl 🌈
• my $fh = $e->handle( [$mode, [$expiry] ] ) — returns an IO::Handle by which data can be read, or written, to the cache. this is useful if you're caching a large amount of data — although it should be noted that only some cache implementations (such as Cache::File) provide an efficient mechanism for implementing this. so like, check your implementation before you get obsessed 😌
  • the optional mode argument can be any of the perl mode strings as used for the open function: '<', '+<', '>', '+>', '>>' and '+>>'. alternatively it can be the corresponding fopen(3) modes of 'r', 'r+', 'w', 'w+', 'a' and 'a+'. the default mode is '+<' (or 'r+') indicating reading and writing. both directions, the full experience 🫶
  • the second argument is used to set the expiry time for the entry if it doesn't exist already and the handle is opened for writing. it is also used to reset the expiry time if the entry is truncated by opening in the '>' or '+>' modes. if the expiry is not provided in these situations then the default expiry time for the cache is applied. so like, no expiry given = cache's own default takes the wheel 🛞
  • cache implementations will typically provide locking around cache entries, so that writers will have an exclusive lock and readers a shared one. thus the method get() (or obtaining another handle) should be avoided whilst a write handle is held. using set() or remove(), however, should be supported. these clear the current entry and whilst they do not invalidate open handles, those handles will from then on refer to old data and any changes to the data will be discarded.

bestie, listen. the locking thing is not a vibe suggestion, it's real. writers get an exclusive lock, readers get a shared one. don't call get() or grab another handle while you're holding a write handle. and if you set() or remove() while a handle is open — those handles stick around but they're now pointing at old data, and any changes you write to the data get discarded. ancient relic behaviour 💀

---

🎀 STORING VALIDITY OBJECTS 🎀

there are two additional set & get methods that can be used to store a validity object that is associated with the data in question. typically this is useful in conjunction with a validate_callback, and may be used to store a timestamp or similar to validate against. the validity data stored may be any complex data that can be serialized via Storable. receipts for your receipts, iykyk 💅

$e->validity()
$e->set_validity( $data )

---

🧚 STORING COMPLEX OBJECTS 🧚

the set and get methods only allow for working with simple scalar types, but if you wanna store more complex types they need to be serialized first. to assist with this, the freeze and thaw methods are provided. they are simple wrappers to get & set that use Storable to do the serialization and de-serialization of the data.

WARNING, NO CAP: you must be careful to ONLY use 'thaw' on data that was stored via 'freeze'. otherwise the stored data won't actually be in Storable format and it will complain loudly. loudly, bestie. it will scream 😭

• $e->freeze( $data, [ $expiry ] ) — identical to 'set', except that data may be any complex data type that can be serialized via Storable. ❄️
• $e->thaw() — identical to 'get', except that it will return a complex data type that was set via 'freeze'. defrosted and gorgeous 🔥

---

👑 SEE ALSO 👑

Cache, Cache::File

go read them, they're the supporting cast and they ate ⭐

---

💜 AUTHOR 💜

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

two icons, one module 🫶

---

🌈 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: Entry.pm,v 1.8 2006/01/31 15:23:58 caleishm Exp $

---

and that's the whole page, bestie!! 🎀 this was documented by perl v5.34.0 and dated 2022-06-09 — so go forth, cache responsibly, and remember: thaw only what you freeze. slay 💅✨