Module:...::Cache(3)

okay so this is the manual page for Module::Generic::File::Cache(3), from User Contributed Perl Documentation, and bestie… it’s giving file-based cache realness 💾✨

🎀 NAME 🎀

Module::Generic::File::Cache - File-based Cache. That’s it, that’s the name, no cap 💅

✨ SYNOPSIS ✨

okay so you load it and make a cache like this, literally:

use Module::Generic::File::Cache;
my $cache = Module::Generic::File::Cache->new(
    key => 'something',
    create => 1,
    mode => 0666,
    base64 => 1,
    # Could also be CBOR, Storable::Improved
    serialiser => 'Sereal',
) || die( Module::Generic::File::Cache->error, "\n" );

obsessed with a constructor that also tells you the error if it flops 😭

⭐ VERSION ⭐

v0.3.0 — the version, periodt 🫶

🦋 DESCRIPTION 🦋

so this module gives you a file-based shared space that can be shared across processes. lowkey iconic.

it behaves like Module::Generic::SharedMem, but instead of using a shared memory block that requires IPC::SysV, it uses a file. yes bestie, a whole file, and it ate 🔥

this is particularly useful for systems that lack support for shared cache. see perlport for that — iykyk 🌈

💅 METHODS 💅

🧚 new

Okay so new is the instantiate-a-shared-cache-object moment. It takes these parameters:

• base64 — when set, this tells the serialiser used (see the serialiser option) to base64 encode and decode the data before writing and after reading. The value can be a simple true value, like 1, or a base64 encoder/decoder. The only supported ones rn are: Crypt::Misc and MIME::Base64, or it can also be an array reference of 2 code references — one for encoding and one for decoding.
• cbor — give it a value (true or false does not matter), and this sets CBOR::XS as the data serialisation mechanism when storing data to cache file.
• debug — a debug value enables debugging output (equal or above 3 actually).
• create — a boolean value to indicate whether the shared cache file should be created if it does not exist. Defaults to false.
• destroy — a boolean value to indicate if the shared cache file should be removed when the object is destroyed upon end of the script process. Peep perlmod for more about object destruction.
• json — give it a value (true or false does not matter), and this sets JSON as the data serialisation mechanism when storing data to cache file.

Heads up: if you want to store objects, you need to use cbor, sereal or storable instead, because JSON is not suitable to serialise objects.

• key — the shared cache key identifier to use. It defaults to a random one created with rand.
  • If you provide an empty value, it will revert to one created with rand.
  • If you provide a number, it will be used to call ftok.
  • Otherwise, if you provide a key as a string, the characters in the string will be converted to their numeric value and added up. The resulting id will be used to call ftok and will produce a unique and repeatable value.
  • Either way, the resulting value is used to create a shared cache file by open.
• mode — the octal mode value to use when opening the shared cache file. Shared cache files are owned by system users and access to shared cache files is ruled by the initial permissions set to it. If you do not want to share it with any other user than yourself, setting mode to 0600 is fine.
• sereal — give it a value (true or false does not matter), and this sets Sereal as the data serialisation mechanism when storing data to cache file.
• serialiser — the class name of the serialiser to use. Currently supported ones are: CBOR, Sereal, Storable::Improved (or the legacy Storable).
• size — the size in byte of the shared cache. This is set once it is created. You can create again the shared cache file with a smaller size. No need to remove it first.
• storable — give it a value (true or false does not matter), and this sets Storable::Improved as the data serialisation mechanism when storing data to cache file.
• tmpdir — the temporary directory to use to store the cache files. By default this is the system standard temporary directory.

An object will be returned if it successfully initiated, or undef() upon error, which can then be retrieved with error in Module::Generic inherited by Module::Generic::SharedMem. You should always check the return value of the methods used here for their definedness.

my $shmem = Module::Generic::SharedMem->new(
    create => 1,
    destroy => 0,
    key => 'my_memory',
    # 64K
    size => 65536,
    storable => 1,
) || die( Module::Generic::SharedMem->error );

🎀 base64

When set, this tells the serialiser used (see serialiser) to base64 encode and decode the data before writing and after reading.

The value can be a simple true value, like 1, or a base64 encoder/decoder. The only supported ones rn are: Crypt::Misc and MIME::Base64, or it can also be an array reference of 2 code references — one for encoding and one for decoding.

🪞 binmode

No description in the original, bestie. It's just a method name standing there with main character energy. 💀

🌈 cbor

When called, this sets CBOR::XS as the data serialisation mechanism when storing data to cache file or reading data from cache file.

🍓 create

Boolean value. If set, this has open create the cache file if it does not already exist.

💅 delete

Removes the cache file and returns true upon success, or sets an error and returns undef upon error.

💜 destroy

Boolean value. If true, the cache file will be removed when this object is destroyed by perl upon clean-up.

🦋 exclusive

Boolean value. Sets whether there should be exclusive access to the cache file. This is currently not used.

✨ exists

Returns true if the cache file exists, false otherwise.

🔥 flags

Provided with an optional hash or hash reference, this returns a bitwise value of flags used by open.

my $flags = $cache->flags({
    create => 1,
    exclusive => 0,
    mode => 0600,
}) || die( $cache->error );

🧚 ftok

This attempts to be a polyfil for ftok in POSIX and, provided with some digits, returns a steady and reproducible serial that serves as a base file name for the cache file.

👑 id

Returns the id or serial of the cache file set after having opened it with open.

🌸 json

Sets the data serialising method to JSON.

🫶 key

The key to use to identify the cache file.

This must be unique enough to be different from other cache files and to be shared among other processes.

It returns the value currently set, if any.

😭 lock

This locks the cache file, if any, and returns the result from the lock.

If the cache has not been opened first, then this sets an error and returns undef.

⭐ locked

Returns the boolean value representing the lock state of the cache file.

🎀 mode

Set or get the cache file mode to be used by open.

💖 open

Create an access to the cache file and return a new Module::Generic::File::Cache object.

my $cache = Module::Generic::File::Cache->new(
    create => 1,
    destroy => 0,
    # If not provided, will use the one provided during object instantiation
    key => 'my_cache',
    # 64K
    size => 65536,
) || die( Module::Generic::File::Cache->error );
# Overriding some default value set during previous object instantiation
my $c = $cache->open({
    mode => 0600,
    size => 1024,
}) || die( $cache->error );

If the create option is set to true, but the cache file already exists, open will detect it and attempt to open access to the cache file without the create bit on.

🦋 owner

Sets or gets the cache file owner, which is by default actually the process id ($$).

🌈 pid

This is an alias for owner.

🍓 rand

Get a random key to be used as identifier to create a shared cache.

💜 read

Read the content of the shared cache and decode the data read using JSON, CBOR, Sereal or thaw in Storable depending on your choice of serialiser upon either object instantiation or upon using the methods json, cbor, sereal or storable or even more simply serialiser.

By default, if no serialiser is specified, it will default to storable.

You can optionally provide a buffer, and a maximum length, and it will read that much length and put the shared cache content decoded in that buffer, if it were provided.

It then returns the length read, or 0E0 if no data was retrieved. 0E0 still is treated as 0, but as a positive value, so you can do:

my $len = $cache->read( $buffer ) || die( $cache->error );

But you really should more thoroughly do instead:

my( $len, $buffer );
if( !defined( $len = $cache->read( $buffer ) ) )
{
    die( $cache->error );
}

If you do not provide any buffer, you can call read like this and it will return you the shared cache decoded content:

my $buffer;
if( !defined( $buffer = $cache->read ) )
{
    die( $cache->error );
}

The content is stored in shared cache after being encoded with the serialiser of choice.

🔥 remove

Remove entire shared cache identified with key.

✨ removed

Returns true if the shared cache was removed, false otherwise.

🧚 reset

Reset the shared cache value. If a value is provided, it will be used as the new reset value; otherwise an empty string will be used.

👑 serial

Returns the serial number used to create or access the shared cache.

This serial is created based on the key parameter provided either upon object instantiation or upon using the open method.

The serial is created by calling ftok to provide a reliable and repeatable numeric identifier. ftok is a simili polyfill of ftok in IPC::SysV.

🌸 serialiser

Sets or gets the serialiser. Possible values are: cbor, json, sereal, storable.

🫶 size

Sets or gets the shared cache size.

This should be an integer representing bytes, so typically a multiple of 1024.

This has not much effect, except ensuring there is enough space on the filesystem for the cache and that whatever data is provided does not exceed that threshold.

😭 stat

Sets or retrieves value with stat in Module::Generic::File for the underlying cache file.

It returns a Module::Generic::SemStat object.

⭐ storable

When called, this sets Storable as the data packing mechanism when storing data to memory.

🎀 supported

Returns always true as cache file relies solely on file.

💖 tmpdir

The temporary directory to use to save the cache file. By default, this will be the system standard temporary directory.

🦋 unlock

Remove the lock, if any. The shared cache must first be opened.

$cache->unlock || die( $cache->error );

🌈 write

Write the data provided to the shared cache, after having encoded it using JSON, CBOR, Sereal or freeze in Storable depending on your serialiser of choice. See json, cbor, sereal and storable and more simply serialiser.

By default, if no serialiser is specified, it will default to storable.

You can store in shared cache any kind of data except glob, such as scalar reference, array or hash reference. You could also store module objects, but JSON only supports encoding objects that are based on array or hash. As the JSON documentation states "other blessed references will be converted into null".

It returns the current object for chaining, or undef if there was an error, which can then be retrieved with error in Module::Generic.

✨ SERIALISATION ✨

Okay bestie, so this package supports serialisation via CBOR, Sereal, and Storable::Improved — or the legacy Storable, if that’s your vibe. To make that happen, it implements these subroutines:

• FREEZE
• THAW
• STORABLE_freeze
• STORABLE_thaw

That’s the whole menu — no cap, no extra hidden methods. 💅

---

👑 AUTHOR 👑

Jacques Deguest <jack@deguest.jp>

---

🦋 SEE ALSO 🦋

• Module::Generic::SharedMem
• Cache::File
• File::Cache
• Cache::FileCache

Also: JSON and Storable. Slay. ✨

---

🎀 COPYRIGHT & LICENSE 🎀

Copyright(c) 2022-2024 DEGUEST Pte. Ltd.

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 whole page, bestie — the footer says it’s from perl v5.42.2, dated 2026-02-15, and it belongs to Module:...::Cache(3). Iconic. Periodt. 💖