Module:...aredMem(3)

🦋 Module:...aredMem(3) — User Contributed Perl Documentation 🦋

okay so this is the Module:...aredMem(3) page from User Contributed Perl Documentation, and it's literally all about Module::Generic::SharedMem. Bestie, we're doing shared memory manipulation and we're doing it thoroughly. ✨

💖 NAME 💖

Module::Generic::SharedMem — shared memory manipulation. That's the whole name and the whole vibe. 💅

✨ SYNOPSIS ✨

group chat recap: check IPC::SysV support, make a shared memory object, poke every option, and here's the code exactly as the page gives it. no cap:

# Check if IPC::SysV is supported on this system
if( Module::Generic::SharedMem->supported )
{
    my $shmem = Module::Generic::SharedMem->new( key => 'some_identifier' ) ||
        die( Module::Generic::SharedMem->error );
}

my $shmem = Module::Generic::SharedMem->new(
    # Create if necessary, or re-use if already exists
    create => 1,
    # Self-destroy upon end of object. Default to false
    destroy => 0,
    # make access exclusive
    exclusive => 1,
    key => 'some_identifier',
    mode => 0666,
    # 100K
    size => 102400,
    debug => 3,
) || die( Module::Generic::SharedMem->error );

# Check if it already exists
if( $shmem->exists )
{
    # do something
}

$shmem->create(0);
$shmem->destroy(0);
$shmem->exclusive(0);
# Then get the bitwise flags based on those options set above:
my $flags = $shmem->flags;
# or specify overriding values:
my $flags = $shmem->flags({
    create => 0,
    destroy => 0,
    exclusive => 0,
    mode => 0644,
});

my $s = $shmem->open || die( $shmem->error );

# Get the shared memory id
my $id = $s->id;

my $key = $s->key;

# Get the actual key used in interacting with shared memory
# You should not mess with this unless you know what you are doing
my $shem_key = $s->serial;

use Module::Generic::SharedMem qw( :all );
$s->lock( LOCK_EX ) || die( $s->error );
# Is it locked?
my $is_locked = $s->locked;

# example: 0666
my $mode = $s->mode;
my $s = $shmem->open || die( $shmem->error );

# Actually the process pid
my $owner = $s->owner;

# The semaphore pid
my $sempid = $s->pid;

# Get a random key to use to create shared memory block
my $random_key = $shmem->rand;

my $data = $s->read;
my $buffer;
$s->read( $buffer );
# You can control how much to read and allocate a buffer to put the read data onto
# Data is automatically transcoded using Storable::Improved::thaw
my $len = $s->read( $buffer, 1024 ) || die( $s->error );

$s->remove;

my $semaphore_id = $s->semid;

# or $s->size;
my $shared_mem_size = $shmem->size;

# See Module::Generic::SemStat doc
my $stat = $s->stat;

# See Module::Generic::SharedStat doc
my $stat = $s->shmstat;

# Remove lock
$s->unlock;

# Data is automatically transcoded using Storable::Improved::freeze
$s->write( $data ) || die( $s->error );

🏷️ VERSION 🏷️

v0.5.4

🌸 DESCRIPTION 🌸

Module::Generic::SharedMem gives you an easy to use api to manipulate shared memory block. See perlipc for more information. 🫶

platform check, bestie: as stipulated in perlport, this is not supported on the following platforms: android, dos, MSWin32, OS2, VMS and Risc OS. 💀

You can check if the system is supported with supported:

if( Module::Generic::SharedMem->supported )
{
    # do something
}

This module only works with reference data, such as array, hash or reference to scalar. Anything that CBOR::XS, Sereal. or Storable::Improved knows how to freeze in Storable::Improved and thaw in Storable::Improved. ✨

🐞 DEBUGGING 🐞

To list all used shared memory, at least on Unix type systems such as Linux or FreeBSD (including MacOSX), use:

ipcs -m

🛠️ METHODS 🛠️

🆕 new

This instantiates a shared memory object. It takes the following parameters, and yes, every single one matters:

• cbor — Provided with a value (true or false does not matter), and this will set CBOR::XS as the data serialisation mechanism when storing data to memory or reading data from memory. 🌈
• debug — A debug value will enable debugging output (equal or above 3 actually). 🐞
• create — A boolean value to indicate whether the shared memory block should be created if it does not exist. Default to false.
• destroy — A boolean value to indicate if the shared memory block should be removed when the object is destroyed upon end of the script process. See perlmod for more about object destruction.
• destroy_semaphore — A boolean value to indicate if the semaphore should be removed when the object is destroyed upon end of the script process. See perlmod for more about object destruction. destroy_semaphore is automatically enabled if destroy is set to true. Thus, one can deactive auto removal of the shared memory block, but enable auto removal of the semaphore. This is useful when there are two processes accessing the same shared memory block and one wants to give the first process the authority to create and remove the shared memory block, while the second only access and write to the shared memory block, but does not remove it. Still to avoid having semaphores surviving the process, by enabling this option and disabling destroy, it will remove the semaphore and leave the shared memory. 💅
• exclusive — A boolean value to set the shared memory as exclusive. This will affect the flags set by flags which are used by open.
• json — Provided with a value (true or false does not matter), and this will set JSON as the data serialisation mechanism when storing data to memory or reading data from memory.
• key — The shared memory key identifier to use. It defaults to IPC::SysV::IPC_PRIVATE. If you provide an empty value, it will revert to IPC::SysV::IPC_PRIVATE. If you provide a number, it will be used to call ftok in IPC::SysV. Otherwise, if you provide a key as string, the characters in the string will be converted to their numeric value and added up. The resulting id, called "project id" by IPC::SysV, will be used to call ftok in IPC::SysV and will produce an hopefully unique and repeatable value. Either way, the resulting value is used to create a shared memory segment and a semaphore by open. 🔑
• mode — The octal mode value to use when opening the shared memory block. Shared memory are owned by system users and access to shared memory segment 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 — Provided with a value (true or false does not matter), and this will set Sereal as the data serialisation mechanism when storing data to memory or reading data from memory.
• serialiser — You can provide the serialiser with this option. Possible values are: cbor, json, sereal, storable.
• size — The size in byte of the shared memory. This is set once it is created. You can create again the shared memory segment with a smaller size, but not a bigger one. If you want to increase the size, you would need to remove it first.
• storable — Provided with a value (true or false does not matter), and this will set Storable::Improved as the data serialisation mechanism when storing data to memory or reading data from memory.

An object will be returned if it successfully initiated, or undef() upon error, which can then be retrieved with Module::Generic::SharedMem->error. 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,
) || die( Module::Generic::SharedMem->error );

📍 addr

Returns the address of the shared memory segment once it has been attached to this address space. 💖

🧲 attach

Attach the shared memory segment to this address space and returns its address.

Upon error, it returns undef and sets an error that can be retrieved with the error method:

my $addr = $shem->attach || die( $shem->error );

A shared memory segment object must be first created with the open method, because attach calls shmat in IPC::SysV with the shared memory id and this id is returned upon using the open method. ✨

🌈 cbor

When called, this will set CBOR::XS as the data serialisation mechanism when storing data to memory or reading data from memory.

🆕 create

Set or get the boolean value to true to indicate you want to create the shared memory block if it does not exist already. Default to false.

🗑️ delete

This is an alias for remove.

💀 destroy

Set or get the boolean value to indicate that the shared memory should be automatically destroyed when the module object is destroyed. See perlmod for more information about module object destruction.

🫳 detach

Quoting the IPC documentation, this detaches the shared memory segment located at the address specified by attach from this address space.

It returns undef if it is not attached anymore, but without setting an error.

👑 exclusive

Set or get the boolean value to affect the open flags in exclusive mode.

🔍 exists

Checks if the shared memory identified with key exists.

It takes the same arguments as open and returns 1 if the shared memory exists or 0 otherwise.

It does this by performing a shmget in perlfunc such as:

shmget( $shared_mem_key, $size, 0444 );

This will typically return the shared memory id if it exists or undef() with an error set in $! by perl otherwise. 💀

🚩 flags

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

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

🆔 id

Returns the id of the shared memory once it has been opened with open.

my $s = $shmem->open || die( $shmem->error );
my $id = $s->id;

🍓 json

When called, this will set JSON as the data serialisation mechanism when storing data to memory or reading data from memory.

🔑 key

Sets or gets the shared memory key identifier.

$shem->key( 'some_identifier' );

🔒 lock

It takes an optional bitwise lock value, and defaults to LOCK_SH if none is provided and issues a lock on the shared memory. 💅

locked 💅

Returns a positive value when a lock is active, or 0 when there's no active lock. No cap.

That value? It's the bitwise value of the lock that's being used. So like, it's not just "yes/no", it's giving you the receipts of which lock. 🔥

mode 🎀

Sets or gets the mode for the shared memory, as used by open:

$shmem->mode( 0666 );
my $s = $shmem->open || die( $shmem->error );

So you set the vibe once and then open walks in wearing it. Slay.

op 🧚

Issues an operation on the semaphore <https://en.wikipedia.org/wiki/Semaphore_(programming)>.

The value you provide should be a set of 3. Like, a little trio. Iconic.

＄s->op( @{$Module::Generic::SharedMem::SEMOP_ARGS->{(LOCK_SH)}} ) ||
    die( $s->error );

Heads up bestie: that ＄ up there is a fullwidth dollar sign, straight from the original page — don't "fix" it, fr fr.

open 👑

Creates or accesses a shared memory segment and returns a new Module::Generic::SharedMem object. It takes an optional hash or hash reference with parameters such as key, mode, size, and semid.

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

If you call it on an already opened object, it reuses the existing shared memory segment and semaphore, creating a new object that shares the same resources. That's the whole point, honestly — it's super useful in threaded applications so every thread can access the same shared memory segment safely. Teamwork, but make it syscalls. 🫶

In threaded applications, the shared memory segment must be opened in the main thread before starting threads to ensure thread-safety. Like, main character energy first, then the entourage. The module automatically manages semaphore reuse via a shared repository ($SERIAL2SEMID) or the current object's semaphore ID, which means thread-safe operations with zero extra configuration from you. No cap.

require threads;
require threads::shared;
threads->import();
threads::shared->import();
my $shem = Module::Generic::SharedMem->new(
    debug => $DEBUG,
    key => 'my_memory',
    size => 65536,
    mode => 0666,
    create => 1,
) || die( Module::Generic::SharedMem->error );
my $obj = $shem->open({ mode => 'w' }) || die( $shem->error );
my @threads;
for(1..3)
{
    push @threads, threads->create(sub
    {
        my $tid = threads->tid();
        my $sh = $obj->open();
        if( !defined( $sh ) )
        {
            warn( "Error with thread $tid: unable to open shared memory segment: ", $obj->error );
            return(0);
        }
        my $data = $sh->read();
        my $old_counter = $data->{counter};
        $data->{counter}++;
        $sh->write( $data ) || return(0);
        return(1);
    });
}
my $success = 1;
for my $thr ( @threads )
{
    my $result = $thr->join();
    $success &&= $result;
}
my $data = $obj->read();
# $data->{counter} is 3, and $success is true

✨ Parameters:

• key — the shared memory key identifier. Defaults to the key set during object instantiation, or IPC::SysV::IPC_PRIVATE.
• mode — the octal mode for the shared memory (e.g., 0600 for owner-only access). Defaults to the mode set during object instantiation.
• size — the size of the shared memory segment in bytes. Defaults to the size set during object instantiation.
• semid — an explicit semaphore ID to use, overriding automatic semaphore management.

If the create option is set to true, but the shared memory already exists, open will detect it and attempt to open access to the shared memory without the create bit on, which is IPC::SysV::IPC_CREAT.

Returns a new Module::Generic::SharedMem object on success, or undef on error, with the error accessible via error in Module::Generic. 😭

my $s = $shem->open({ mode => 'r', size => 1024 }) || die( $shem->error );

owner 💜

Sets or gets the shared memory owner, which is by default actually the process id ($$). Like, it literally owns it. Periodt.

pid 🦋

Gets the semaphore <https://en.wikipedia.org/wiki/Semaphore_(programming)> pid once the shared memory has been opened.

my $pid = $s->pid || die( $s->error );

rand 🌸

Gets a random key to be used as the identifier when creating a shared memory. Chaos, but make it cryptographic-adjacent. 🎲

read 📖

Reads the content of the shared memory and decodes the data read using JSON, CBOR, Sereal or thaw in Storable::Improved — 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. For example:

my $s = Module::Generic::SharedMem->new( cbor => 1 ) ||
    die( Module::Generic::SharedMem->error );
# or
$s->cbor(1);
# or
my $s = Module::Generic::SharedMem->new( serialiser => 'cbor' ) ||
    die( Module::Generic::SharedMem->error );

By default, if no serialiser is specified, it will default to storable. (The reliable bestie. 💅)

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

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

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

But you really should more thoroughly do instead:

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

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

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

Real talk: that 0E0 thing is a little gremlin — it's truthy-looking but it's numerically zero. Use defined checks, not truthiness. Your future self will thank you. 🙈

remove 💀

Removes entire the shared memory identified with key. Yes, the original really does say "Remove entire the shared memory" — we keep the lore intact. Bye bestie, segment's gone. 👋

remove_semaphore 🧹

Removes the semaphore associated with the shared memory. Decluttering the friend group.

removed ✅

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

removed_semaphore 🫧

Returns true if the semaphore has been removed, false otherwise.

reset 🔄

Resets the shared memory value. If a value is provided, it will be used as the new reset value, otherwise an empty string will be used. Fresh start, clean slate, main character rebirth arc. ✨

semid 🎟️

Returns the semaphore <https://en.wikipedia.org/wiki/Semaphore_(programming)> id once the shared memory has been opened. See perlipc for more information about semaphore and perlfunc. iykyk.

sereal 🍓

When called, this will set Sereal as the data serialisation mechanism when storing data to memory or reading data from memory.

serial 🔢

Returns the serial number used to create or access the shared memory segment.

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 in IPC::SysV to provide a reliable and repeatable numeric identifier. It's giving "consistent, dependable, will not ghost you". 🔥

serialiser 🎀

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

shmstat 📊

Returns an Module::Generic::SharedStat object representing the current shared memory properties. Receipts. ✨

size 📏

Sets or gets the shared memory block size.

This should be an integer representing bytes, so typically a multiple of 1024. Like, do the math bestie. 🧮

stat 🎯

Sets or retrieves a value with semaphore <https://en.wikipedia.org/wiki/Semaphore_(programming)>.

If one parameter only is provided, it returns its corresponding value set.

It performs:

# Get the semaphore id
my $id = $s->semid;
my $value = semctl( $id, $sem, IPC::SysV::GETVAL, 0 );

When 2 parameters are provided, this is treated as a key-value pair and sets the value for the corresponding key.

It performs:

my $id = $s->semid;
semctl( $id, $sem, IPC::SysV::SETVAL, $val )

If no parameter is provided, it returns a Module::Generic::SemStat object in scalar context, or an array of values in list context. Context matters, always. 💅

storable 🍒

When called, this will set Storable::Improved as the data serialisation mechanism when storing data to memory or reading data from memory.

supported 🌈

Returns true if IPC shared memory segments are supported by the system, and false otherwise. Basically a vibe check on your OS.

unlock 🔓

Removes the lock, if any. The shared memory must first be opened.

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

Free at last. 🦋

write ✍️

Writes the data provided to the shared memory, after having encoded it using JSON, CBOR, Sereal or freeze in Storable::Improved depending on your choice of serialiser. See json, cbor, sereal and storable.

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

You can only store references in shared memory — such as a scalar reference, an array or a hash reference. You could also store module objects, but note that if you choose JSON as a serialiser for your shared data, 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 if you're using other reference types, you might want to use CBOR, Sereal or Storable instead. Not me watching your object turn 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 ✨

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.

Four little subroutines doing the absolute most, and honestly? Obsessed. 🫶🎀

💖 THREAD & PROCESS SAFETY 💖

Okay bestie, this is the part where Module::Generic::SharedMem shows off its safety-girlie era ✨ It’s built for safe multi-process and multi-threaded access to shared memory using System V IPC. It uses semaphores to guard concurrent access, so data integrity stays iconic across processes and threads. In threaded applications, the module uses a shared repository ($SERIAL2SEMID) and thread-safe locking to manage semaphore reuse, letting multiple threads access the same shared memory segment without conflicts. No cap.

Key considerations for thread and process safety are giving:

• Main Thread Initialization — In threaded apps, the shared memory segment must be opened in the main thread before starting worker threads. That way the semaphore ID gets stored in the shared repository ($SERIAL2SEMID) or is accessible via the opened object, so worker threads can reuse it safely. Slay.

my $shem = Module::Generic::SharedMem->new( key => 'my_memory', create => 1 );
my $obj = $shem->open({ mode => 'w' });
my @threads = map {
    threads->create(sub {
        my $sh = $obj->open();
        # Work with $sh
    });
} 1..10;

• Semaphore Reuse — When you call open on an already opened object (e.g., $obj->open()), the module reuses the existing semaphore ID, ensuring all threads operate on the same shared memory segment. This is thread-safe thanks to internal locking mechanisms. Obsessed.
• Process Safety — For multi-process applications, semaphores prevent concurrent access issues. Each process can open the shared memory segment using the same key, and the module ensures safe access via semaphore operations.
• Cleanup — Shared memory and semaphores are system-wide resources and persist until explicitly removed or the system is rebooted. Use remove to clean up shared memory and remove_semaphore for semaphores, especially in daemonized or mod_perl environments. The destroy and destroy_semaphore options can automate cleanup when the object is destroyed, but manual removal is recommended for explicit control.

$obj->remove() if $obj->exists();

• Thread Limitations — While thread-safe, this module is primarily designed for inter-process communication. In threaded environments, ensure proper initialization and avoid creating new shared memory segments in worker threads to prevent semaphore conflicts.

Bestie, this is important: shared memory and semaphores don’t magically vanish when your object goes poof 💀 They’re system-wide resources. Clean up on purpose.

For debugging shared memory and semaphore usage on Unix-like systems (e.g., Linux, FreeBSD, macOS), use:

ipcs -m  # List shared memory segments
ipcs -s  # List semaphores
ipcrm -m <shmid>  # Remove shared memory
ipcrm -s <semid>  # Remove semaphore

---

🌟 AUTHOR 🌟

Jacques Deguest <jack@deguest.jp>

---

🔭 SEE ALSO 🔭

• Module::Generic
• Module::Generic::SemStat
• Module::Generic::SharedStat
• perlipc
• perlmod
• IPC::Semaphore

---

📜 COPYRIGHT & LICENSE 📜

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

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.

---

Okay that’s the whole manual page, bestie 💅 source/version vibe: perl v5.42.2; date: 2026-02-15; and yes, this is the User Contributed Perl Documentation for Module:...aredMem(3). Go forth and share that memory safely 🫶✨