PDL::DiskCache(3pm)

💾 PDL::DiskCache — the perl manual page, but make it bestie PDL::DiskCache(3pm) ✨

okay so. this is the User Contributed Perl Documentation entry for a thing called PDL::DiskCache and it is literally the "Non-memory-resident array object" of your dreams. your PDLs live on disk, only a few hang out in RAM at a time, and you get to pretend you're working with a normal perl list. iconic behavior honestly 💅

---

🌸 NAME 🌸

PDL::DiskCache — a Non-memory-resident array object. it's giving "array, but it lives on disk and only visits memory". 🦋

---

✨ SYNOPSIS ✨

the NON-OO way, no objects no drama:

use PDL::DiskCache;
tie @a,'PDL::DiskCache', \@files, \%options;
imag $a[3];

the OO way, main character energy:

use PDL::DiskCache;
$x = diskcache(\@files,\%options);
imag $x->[3];

or, if you're feeling fancy:

use PDL::DiskCache;
$x = PDL::DiskCache->new(\@files,\%options);
imag $x->[4];

and the args, bestie:

• \@files — an array ref containing a list of file names 📁
• \%options — a hash ref containing options for the PDL::DiskCache object (go peek at "TIEARRAY" below for the deets) 🎀

---

🫶 DESCRIPTION 🫶

so. a PDL::DiskCache object is a perl "tied array" and it is perfect for when you have to look at a huge collection of PDLs one or a few at a time — think tracking features through an image sequence, that vibe. 🌈

the glow-up: you write your prototype code using a plain perl list of a few PDLs, and then you scale it to millions of PDLs just by handing that same prototype code a DiskCache tied array instead of a native perl array. no rewrite, no tears. periodt. 💖

the individual PDLs are stored on disk and a few of them get swapped into memory on a FIFO basis. you can set whether the data are read-only or writeable. 👑

by default, PDL::DiskCache uses FITS files to represent the PDLs — but lowkey you can use any sort of file at all, because the read/write routines are the only place where it examines the underlying data. you can specify the routines to use at construction time (or, of course, subclass PDL::DiskCache). slay.

⚠️ items are swapped out on a FIFO basis, so if you have 10 slots and an expression with 10 items in it then you're OK (but you probably want more slots than that). but if you use more items in an expression than there are slots, thrashing will occur! 💀

the hash ref interface is kept for historical reasons (elder emoji respect 🫡) — you can access the sync() and purge() method calls directly from the returned array ref.

😭 Shortcomings & caveats 😭

• there's no file locking, so you could really hose yourself by having two of these things going at once on the same files. not the vibe. 🙈
• since this is a tied array, things like Dumper traverse it transparently. that is sort-of good but also sort-of dangerous. you would not want to PDL::Dumper::sdump() a large PDL::DiskCache, for example — that would defeat the purpose of using a PDL::DiskCache in the first place. 💀

👑 Author, license, no warranty 👑

Copyright 2001, Craig DeForest 🎀

this code may be distributed under the same terms as Perl itself (license available at <http://www.perl.org>). copying, reverse engineering, distribution, and modification are explicitly allowed so long as this notice is preserved intact and modified versions are clearly marked as such. 🫶

if you modify the code and it's useful, please send a copy of the modified version to cdeforest@solar.stanford.edu. 💌

this package comes with NO WARRANTY. (say it with me. no. warranty. 💅)

---

🔥 FUNCTIONS 🔥

diskcache

object constructor. that's it, that's the whole job.

$x = diskcache(\@f,\%options);

Options

• see the TIEARRAY options, below. 👇

TIEARRAY

tied-array constructor; invoked by perl during object construction. perl does the summoning, you just vibe. 🧚

TIEARRAY(class,\@f,\%options)

Options

• ro (default 0) — if set, treat the files as read-only (modifications to the tied array will only persist until the changed elements are swapped out) 🍓
• rw (default 1) — if set, allow reading and writing to the files. because there's currently no way to determine reliably whether a PDL has been modified, rw files are always written to disk when they're swapped out — this causes a slight performance hit. 😭
• mem (default 20) — number of files to be cached in memory at once. 🧠
• read (default \&rfits) — a function ref pointing to code that will read list objects from disk. the function must have the same syntax as rfits: $object = rfits(filename). 📖
• write (default \&wfits) — a function ref pointing to code that will write list objects to disk. the function must have the same syntax as wfits: func(object,filename). ✍️
• bless (default 0) — if set to a nonzero value, then the array ref gets blessed into the DiskCache class for for easier access to the "purge" and "sync" methods. this means that you can say "$x->sync" instead of the more complex "(%{tied @$x})->sync", but "ref $x" will return "PDL::DiskCache" instead of "ARRAY", which could break some code. 🙈 (the original really does say "for for". we do not fix the elders' typos, we respect them. 💅)
• verbose (default 0) — get chatty. 🗣️

purge

remove an item from the oldest slot in the cache, writing to disk as necessary. you also send in how many slots to purge (default 1; sending in -1 purges everything.) 🧹

for most uses, a nice MODIFIED flag in the data structure could save some hassle here. but PDLs can get modified out from under us with slicing and .= — so for now we always assume everything is tainted and must be written to disk. drama but make it necessary. ✨

sync

in a rw cache, flush items out to disk but retain them in the cache. 💾

accepts a single scalar argument, which is the index number of a single item that should be written to disk. passing (-1), or no argument, writes all items to disk, similar to purge(-1).

for ro caches, this is a not-too-slow (but safe) no-op. 🙃

DESTROY

this is the perl hook for object destruction. it just makes a call to "sync", to flush the cache out to disk. 🪦

⚠️ destructor calls from perl don't happen at a guaranteed time, so be sure to call "sync" if you need to ensure that the files get flushed out, e.g. to use 'em somewhere else. don't let your faves get caught in limbo bestie 😭

---

and that's the whole page, mwah 💋 this was perl v5.42.3, dated 2026-08-20, filed under PDL::DiskCache(3pm). go forth and cache responsibly, bestie 🦋💖✨