CHI::D...r::File(3pm)

💖 CHI::Driver::File — the perl manual, but make it bestie 💖

okay so you found the CHI::Driver::File page in the perl docs (section 3pm, modules, you know the vibe) and honestly? it's a banger. let me translate.

---

✨ VERSION ✨

version 0.61 — she's serving, she's stable, she's giving mature release energy 🎀

---

🌸 SYNOPSIS 🌸

like, here's the whole thing, copy it exactly bestie:

use CHI;

my $cache = CHI->new(
    driver         => 'File',
    root_dir       => '/path/to/cache/root',
    depth          => 3,
    max_key_length => 64
);

that's it. that's the whole entrance. iconic. 💅

---

🦋 DESCRIPTION 🦋

so this cache driver literally just... writes your data to the filesystem 💾 like, on disk. which means it can be shared between processes on a single machine, or even across multiple machines if you're using NFS. slay for distributed-ish setups, no cap.

Every single item gets its own file. One item, one file. main character treatment for each entry, periodt.

By default, during a set, here's the choreography: a temporary file gets created, and then it gets atomically renamed to the proper file. is it the most efficient thing ever? no bestie, it's not 🔥 but hear me out — it eliminates the need for locking. if you've got multiple overlapping sets going on, the last one "wins" (survival of the fittest fr fr). and this makes the cache usable in environments like NFS where locking might normally be undesirable. lowkey genius.

By default, the base filename is the key itself, with unsafe characters escaped similar to URL escaping. but if the escaped key is larger than max_key_length (default 248 characters), it will be digested instead. you might wanna lower max_key_length if you're storing a lot of items, because long filenames can be more expensive to work with. not me warning you about your filesystem's feelings 😭

and the files? they get evenly distributed within a multi-level directory structure with a customizable depth, to minimize the time needed to search for a given entry. organization queen 👑

---

💜 CONSTRUCTOR OPTIONS 💜

when you're using this driver, you can pass these options to CHI->new() in addition to the CHI ones. here's the lineup:

• root_dir — the location in the filesystem that will hold the root of the cache. defaults to a directory called 'chi-driver-file' under the OS default temp directory (e.g. '/tmp' on UNIX). this directory gets created as needed on the first cache set, so don't stress, she'll show up when it's time 🫶
• depth — the number of subdirectories deep to place cache files. defaults to 2. you want this large enough that no leaf directory has more than a few hundred files. each non-leaf directory contains up to 16 subdirectories (0-9, A-F). hex girlies rise 🌈
• dir_create_mode — permissions mode to use when creating directories. defaults to 0775.
• file_create_mode — permissions mode to use when creating files, modified by the current umask. defaults to 0666.
• file_extension — extension to append to filename. default is ".dat".

---

🎀 METHODS 🎀

• path_to_key ( $key ) — returns the full path to the cache file representing $key, whether or not that entry actually exists. returns the empty list if a valid path cannot be computed, for example if the key is too long. so like, sometimes she just can't, and that's valid 💀
• path_to_namespace — returns the full path to the directory representing this cache's namespace, whether or not it has any entries.

---

💅 TEMPORARY FILE RENAME 💅

By default, during a set, a temporary file is created and then atomically renamed to the proper file. This eliminates the need for locking. periodt.

but here's the fun part — you can subclass and override the method generate_temporary_filename to either change the path of the temporary filename, or skip the temporary file and rename altogether by having it return undef. DIY queen behavior, obsessed ✨

---

🌟 SEE ALSO 🌟

• CHI

---

👑 AUTHOR 👑

Jonathan Swartz <swartz@pobox.com> — thank you for your service 🫡

---

💖 COPYRIGHT AND LICENSE 💖

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. fr fr, go wild.

---

and that's the whole page bestie, every flag, every default, every path — nothing skipped, nothing invented 💖

perl v5.32.1 · 2021-10-15 · and yes, this is the CHI::D...r::File(3pm) page, that truncated directory name is literally what's printed, don't come for me 🙈

mwah, go cache something responsibly 🦋💜