IPC::Shareable::SharedMem(3)

NAME
IPC::Shareable::SharedMem - Allows access to a shared memory segment via an object oriented interface.

DESCRIPTION
This module provides object oriented access to a shared memory segment. Although it can be used standalone, it was designed for use specifically within the IPC::Shareable library.

SYNOPSIS
    use IPC::Shareable::SharedMem;

    my $seg = IPC::Shareable::SharedMem->new(
        key  => 1234,
        size => 65536,
    );

    $seg->shmwrite($data);

    my $data = $seg->data;

METHODS

  new(%params)
Instantiates and returns an object that represents a shared memory segment.

If for any reason we can't create the shared memory segment, we'll return "undef".

Parameters (must be in key => value pairs):

key

Mandatory, Integer: An integer that references the shared memory segment.

size

Optional, Integer: An integer representing the size in bytes of the shared memory segment. The maximum is Operating System independent.

Default: 1024

flags

Optional, Bitwise Mask: A bitwise mask of options logically OR'd together with any or all of "IPC_CREAT" (create segment if it doesn't exist), "IPC_EXCL" (exclusive access; if the segment already exists, we'll "croak") and "IPC_RDONLY" (create a read only segment).

See IPC::SysV for further details.

Default: 0 (ie. no flags).

mode

Optional, Octal Integer: An octal number representing the access permissions for the shared memory segment. Exactly the same as a Unix file system permissions.

Default: 0666 (User RW, Group RW, World RW).

type

Optional, String: The type of data that will be stored in the shared memory segment. IPC::Shareable uses "SCALAR", "ARRAY" or "HASH".

  id
Sets/gets the identification number that references the shared memory segment.

A warning will be thrown if you try to set the ID after the object is already instantiated, and no change will occur.

  key
Sets/gets the key used to identify the shared memory segment.

Setting this attribute should only be done internally. If it is sent in after the object is already associated with a shared memory segment, we will "croak".

See "key" for further details.

  key_hex($key)
Returns the hex formatted key which appears in "ipcs" calls.

Parameters:

$key

Optional, String: This is always sent in during initialization.

  size
Sets/gets the size of the shared memory segment in bytes. See "size" for further details.

A warning will be thrown if you try to set the size after the object is already instantiated, and no change will occur.

  flags
Sets/gets the flags that the segment will be created with. See "flags" for details.

A warning will be thrown if you try to set the flags after the object is already instantiated, and no change will occur.

  mode
Sets/gets the access permissions. See "mode" for further details.

A warning will be thrown if you try to set the mode after the object is already instantiated, and no change will occur.

  type
Sets/gets the type of data that will be contained in the shared memory segment. See "type" for details.

A warning will be thrown if you try to set the type after the object is already instantiated, and no change will occur.

  data
Returns the data in the shared memory segment, with all NULL pad bytes removed.

Use this method for text data. For binary data where you need all blocks within the segment, use the "shmread" method.

  stat
This method has sub methods that display various system-level information about the memory segment. These sub methods are:

    uid
    gid
    cuid
    cgid
    mode
    segsz
    lpid
    cpid
    nattch
    atime
    dtime
    ctime

Example call:

    my $ctime = $seg->stat->ctime;

  stats
Returns an href of the various system-level stat information:

    {
        uid     => 501,
        gid     => 20,
        cuid    => 501,
        cgid    => 20,
        mode    => 0666,
        segsz   => 65536,
        lpid    => 61270,
        cpid    => 61270,
        nattch  => 0,
        atime   => 1778791348,
        dtime   => 1778791348,
        ctime   => 1778791348,
    }

  stat_list
Returns an array of all the segment's system stat entries. These are what make up the method names of the "$seg->stat" object.

  shmread
Returns the data (and NULL pad bytes) stored in the shared memory segment.

By default, when data is retrieved from the shared memory segment, the data is padded to the right by NULL bytes to fill up the entire size of the segment. This can cause issues when using the space for non serialized data (ie. if you stored "hello" in a 1024 byte segment, the ASCII text wouldn't match).

Typically this method is used when you want all blocks of the segment, such as if you've stored binary data.

For text/ASCII data, use the "data" method which automatically strips NULL pad bytes.

Return: The data if any is stored, empty string if no data has been stored yet, and "undef" if a failure to read occurs.

  shmwrite($data)
Stores the serialized data to the shared memory segment.

Parameters:

    $data

Mandatory, String: Typically, the a serialized data structure.

Return: True on success, false on failure.

  remove
Removes the shared memory segment and returns the resources to the system.

Return: True (1) on success, false (0) on failure.

AUTHOR
Ben Sugars (bsugars@canoe.ca)

MAINTAINED BY
Steve Bertrand <steveb@cpan.org>

SEE ALSO
IPC::Shareable, IPC::Shareable::SharedMem, IPC::ShareLite