Module:...le::Mmap(3)

📦 version 1.1.3, in alpine 3.24

🌸 NAME 🌸

Module::Generic::File::Mmap — it's the MMap File Class, bestie. Yes, that's literally it. This is the Module:...le::Mmap(3) page, btw — user contributed Perl documentation, living its best life.

✨ SYNOPSIS ✨

okay so here's the whole vibe in one go:

use Module::Generic::File::Mmap;
my $cache = Module::Generic::File::Mmap->new(
    create => 1,
    destroy => 1,
    key => 'my key',
    mode => 0666,
    # Other possibilities are: cbor, sereal, storable and json
    serialiser => 'sereal',
    # 256k
    size => 262144,
    base64 => 1,
) || die( Module::Generic::File::Mmap->error, "\n" );

like, that's the entire energy. 🫶

🎀 VERSION 🎀

v0.1.5

💅 DESCRIPTION 💅

So Module::Generic::File::Mmap is out here implementing a whole Mmap cache mechanism using Cache::FastMmap, which — fun fact — is an XS module. Ngl, the api is very similar to its counterpart with Module::Generic::File::Cache and Module::Generic::SharedMem, but it has the slay advantage of sharing data over a file like Module::Generic::File::Cache does, except it's using Mmap and it's very fast. it's giving speed. it's giving range. 🔥

💀 real talk though: you must have installed Cache::FastMmap separately for this module to actually work. If it's not installed, you could still instantiate an object — but you would not be able to get a new object after with "open". so like, it's giving false hope a little bit. 😭

This is particularly useful for systems that lack support for shared memory cache, bestie. See perlport for that whole situation. 🌈

💅 METHODS 💅

🌸 new

This is how you birth a shared mmap cache object, bestie. It takes these params:

debug — a debug value turns on debugging output (and honestly it only actually kicks in at 3 or above, so don't be out here setting it to 1 and wondering why it's quiet 🙈).
cbor — give it any value at all (true or false, doesn't matter, it's giving "presence is enough") and it sets CBOR::XS as your data serialisation mechanism when storing data to the mmap file.
create — a boolean saying whether the shared mmap cache file should be created if it doesn't exist yet. Defaults to false, no cap.
destroy — a boolean saying whether the shared mmap cache file should be removed when the object gets destroyed at the end of the script process. Peep perlmod if you want the whole lore on object destruction.
json — give it a value (true or false, doesn't matter) and it sets JSON as the data serialisation mechanism when storing data to the mmap file. ⚠️ Quick heads up though: if you wanna store objects, you need storable instead, because JSON is literally not suitable for serialising objects. It's just not built for that.
key — the shared mmap cache key identifier to use. Defaults to a random one created with rand. The drama of it all:
- if you provide an empty value, it reverts to one created with rand
- if you provide a number, that number gets used to call ftok
- otherwise, if you provide a key as a string, the characters in the string get converted to their numeric value and added up. That resulting id gets used to call ftok and produces a unique and repeatable value ✨

Either way, the resulting value is used to create a shared mmap cache file by open.

mode — the octal mode value to use when opening the shared mmap cache file. Shared cache files are owned by system users, and access to them is ruled by the initial permissions set on it. If you don't wanna share with anybody but yourself, setting mode to 0600 is fine. Self-care 💅
sereal — give it a value (true or false, doesn't matter) and it sets Sereal as the data serialisation mechanism when storing data to the mmap file.
size — the size in byte of the shared mmap cache. This is set once it's created. You can create the shared mmap cache file again with a smaller size — no need to remove it first, slay.
storable — give it a value (true or false, doesn't matter) and it sets Storable::Improved as the data serialisation mechanism when storing data to the mmap file.

You get an object back if it initiated successfully, or undef() on error — which you can then grab with "error" in Module::Generic, inherited by Module::Generic::SharedMem. And please, always check the return value of the methods used here for definedness. Like actually. 🫶

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

🎀 cache_file

Sets or gets the underlying cache file to use. That's it, that's the whole vibe.

🦋 cbor

When called, this sets CBOR::XS as the data serialisation mechanism when storing data to mmap cache or reading data from mmap cache. Two-way street, icon behaviour.

🌈 create

Boolean value. If set, this makes open create the cache file if it doesn't already exist.

💜 delete

Removes the cache file and returns true upon success — or it sets an error and returns undef upon error. Bye bestie 👋

🍓 destroy

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

⭐ exclusive

Boolean value. Sets whether there should be exclusive access to the cache file. Currently not used, so it's giving decorative. 🙈

🌸 exists

Returns true if the cache file exists, false otherwise. Simple as.

🧚 flags

Hand it an optional hash or hash reference and it returns a bitwise value of the flags used by open. Cute.

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, it returns a steady and reproducible serial that serves as a base file name for the cache file. Reliable king 👑

👑 has_xs

Read-only. Returns true if the XS module Cache::FastMmap is installed on your system, and false otherwise.

💀 id

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

🌸 json

When called, this sets JSON as the data serialisation mechanism when storing data to cache mmap.

🦋 key

The key used to identify the cache file. It 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 hasn't been opened first, then this sets an error and returns undef. So open it first, bestie, please 😭

🎀 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

Creates access to the cache mmap file and returns a new Module::Generic::File::Mmap object. Look at her go:

my $cache = Module::Generic::File::Mmap->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::Mmap->error );
# Overriding some default value set during previous object instantiation
my $c = $cache->open({
    mode => 0600,
    size => 1024,
}) || die( $cache->error );

And 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. She's smart like that.

🌈 owner

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

🍓 rand

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

🔥 read

Reads the content of the shared mmap cache and decodes the data read using JSON, CBOR, Sereal or thaw in Storable, depending on your serialiser of choice — set either upon object instantiation or upon using the methods json or storable.

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

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

Then it returns the length read, or 0E0 if no data was retrieved. And yes — 0E0 still gets treated as 0, but as a positive value, so you can do this:

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

But honestly you really should do this instead, more thoroughly:

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

If you don't provide any buffer, you can call read like this and it'll just hand you the shared mmap cache decoded content:

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

The content is stored in the shared mmap cache after being encoded with freeze in Storable. ✨

💜 remove

Removes the entire shared mmap cache identified with key. Gone. Deleted. Ghosted.

🌸 removed

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

🦋 reset

Resets the shared mmap cache value. If a value is provided, it gets used as the new reset value — otherwise an empty string is used.

🎀 sereal

When called, this sets Sereal as the data serialisation mechanism when storing data to cache mmap.

⭐ serial

Returns the serial number used to create or access the shared mmap 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. And ftok here 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 mmap cache size. This should be an integer representing bytes, so typically a multiple of 1024.

Honestly it has not much effect, except ensuring there's enough space on the filesystem for the cache and that whatever data you throw at it doesn't exceed that threshold. Vibes-based but functional.

🍓 stat

Sets or retrieves the 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::Improved as the data serialisation mechanism when storing data to cache mmap.

👑 supported

Returns always true, because the cache file relies solely on file. Ever-supportive icon 💖

💀 unlock

Removes the lock, if any. The shared mmap cache must first be opened. Like so:

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

🦋 write

Writes the data you provide to the shared mmap cache, after having encoded it using JSON, CBOR, Sereal or freeze in Storable, depending on your serialiser of choice. Peep "json", "cbor", "sereal" and "storable", or more simply "serialiser".

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

You can store any kind of data in the shared mmap cache excepted glob — such as a scalar reference, an array or a 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". So, yeah. 🙈

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

✨ SERIALISATION ✨

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: "FREEZE", "THAW", "STORABLE_freeze" and "STORABLE_thaw". Iconic lineup honestly 🌟

🧵 THREAD SAFETY 🧵

This module is thread-safe by design — provided that:

Each thread creates or uses its own Module::Generic::File::Mmap instance.
Underlying mmap access is managed via Cache::FastMmap, which internally supports safe access via file locks and mmap.
Thawing and serialisation are protected against circular references and duplicated shared state.

No global variables are used. Not a single one. Clean girl aesthetic 💅

🌸 AUTHOR 🌸

Jacques Deguest <jack@deguest.jp>

🎀 SEE ALSO 🎀

Module::Generic::SharedMem, Cache::File, File::Cache, Cache::FileCache

JSON, Storable

💖 COPYRIGHT & LICENSE 💖

okay bestie, the legal bit — but make it cute, because even paperwork deserves a vibe check ✨

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

Like — literally the whole license in one breath: free software, redistribute it, modify it, same terms as Perl itself. No cap, that's the entire deal. Iconic behavior from a module, honestly 💅

and that's a wrap on the whole page, bestie!! 🎀 you made it through every single section and i'm so proud of you fr fr 🌸 this render came to you from perl v5.42.2, dated 2026-02-15 — go forth and mmap responsibly, mwah 💋👑

📦 where this page comes from

alpine 3.24: perl-module-generic-doc 1.1.3-r1 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

Module:...le::Mmap(3)

🌸 NAME 🌸

✨ SYNOPSIS ✨

🎀 VERSION 🎀

💅 DESCRIPTION 💅

💅 METHODS 💅

🌸 new

🎀 cache_file

🦋 cbor

🌈 create

💜 delete

🍓 destroy

⭐ exclusive

🌸 exists

🧚 flags

🔥 ftok

👑 has_xs

💀 id

🌸 json

🦋 key

💜 lock

🎀 locked

⭐ mode

🧚 open

🌈 owner

🍓 rand

🔥 read

💜 remove

🌸 removed

🦋 reset

🎀 sereal

⭐ serial

🧚 serialiser

🌈 size

🍓 stat

🔥 storable

👑 supported

💀 unlock

🦋 write

✨ SERIALISATION ✨

🧵 THREAD SAFETY 🧵

🌸 AUTHOR 🌸

🎀 SEE ALSO 🎀

💖 COPYRIGHT &amp; LICENSE 💖

💖 COPYRIGHT & LICENSE 💖