IPC-Mmap-Share

NAME

IPC::Mmap::Share - Safely share structures among processes using anonymous mmap.

SYNOPSIS

use IPC::Mmap::Share;

            #create an area 10000 bytes big
            my $ref = IPC::Mmap::Share->new(10000);

            #program possibly forks later...
        
            #store the $data (can be either scalar or reference). 
            $ref->set($data);

            #get the data
            my $data = $ref->get;

DESCRIPTION
Overview
The IPC::Mmap::Share was born out of the need to share structures among processes that come from the same ancestor. It tries to do so in a very simple and straightforward manner. Just create an IPC::Mmap::Share object, and use set to store your data and get to get it back.

Internals
This module uses the IPC::Mmap module internally to carry out its mmap tasks. When a new object is initialized, the module uses anonymous mmap (eg. it does not correspond to any real file, just some internal OS buffers) to create the area where it will be storing its data. Get and set are implemented using Storable, by freezing the variable and later thawing it from its storage. Locks are used to protect both reads from and writes to the mmaped area.

Motivation
There are many excellent modules on CPAN which will happily handle all the details of interprocess communication even for complex cases. Some of these modules use shared memory and others use mmap. I needed something that uses b<anonymous> mmap and has a very simple way of operation. For many simple tasks, you may find it useful. For more complex jobs, you may want to take a look at other modules.

METHODS

new(SIZE)

            Just pick a size for the storage area and initialize the object.
            Remember that any variable or structure you are going to share
            must be able to fit in the size you specified.

set(VAR)

            This method will store VAR inside the mmaped area. VAR can be a
            reference to any structure or a simple scalar.

get() This method will retrieve the stored structure or scalar from

the mmaped area and return it.

lock(),unlock()

            In case you want to explicitly lock or unlock the structure, you
            can use these methods.

WARNING

            If the module fails during any of its tasks, it will try to
            croak.

            Don't try to store an undef value.

            Don't try to pass more than one argument to set. All other
            arguments will be ignored. Likewise, if you try to store an
            array, only the first element will get through. Instead, store a
            reference to the array and it will go fine.

            Also, please make sure that you do not try to store something
            bigger than the size you have initialized your object with. The
            module will croak if something like that occurs. If you do not
            know what is the serialization length of your structure, try to
            make a guess. The module unfortunately cannot change the size of
            the mmaped area after object creation.

            If what you are trying to do requires something more complicated
            than that, there are excellent CPAN modules out there which will
            probably suit your needs. Also, if your program is going to do
            LOTS of gets and sets in a short time, you may need a smarter
            locking mechanism. Again, take a look at these other CPAN
            modules.

SEE ALSO

            You may find these excellent modules useful: IPC::SharedCache,
            IPC::ShareLite, IPC::Shareable

BUGS

            Surely there are quite a few. If you see them, report them to
            the proper authorities!..

FUTURE WORK

            Perhaps IPC::Mmap::Share could conveniently subclass IPC::Mmap
            instead of being standalone.

AUTHOR

            IPC::Mmap::Share was written by Athanasios Douitsis
            <aduitsis@cpan.org>

COPYRIGHT

            This program is free software; you can redistribute it and/or
            modify it under the same terms as Perl itself. See
            <http://www.perl.com/perl/misc/Artistic.html>