This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License , or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this software. If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

*** This is beta software -- use at your own risks ***

Introduction

IPC::Shareable allows you to tie a variable to shared memory making it easy to share the contents of that variable with other Perl processes. Scalars, arrays, and hashes can be tied. The variable being tied may contain arbitrarily complex data structures - including references to arrays, hashes of hashes, etc.

Installation

0. Prerequisites:

        -Perl version 5.005_03 or more recent.
        -System V IPC (shmget(2), shmctl(2), etc).
        -Storable.pm, version 0.6 or more recent.

Installation steps:
-from the directory where this file is located, type: perl Makefile.PL make make test make install

Incompatibility Alert

This version contains some incompatiblities from earlier versions of IPC::Shareable. Here's a list of them.

Earlier versions allowed you to use the word B<yes> for true and the word B<no> for false as elements in the options hash. Support for this "feature" is being removed. B<yes> will still act as true (since it is true, in the Perl sense), but use of the word B<no> now emits an (optional) warning and then revert to a false value. This warning will become mandatory in a future release and then at some later date stop working altogether.
Earlier versions used to accept upper-case values of YES/NO as elements in the options hash in addition to yes/no. Support for this has been entirely removed.
Earlier versions would try to allow data of arbitrary length to be tied to shared memory. This well-intentioned (but misguided) approach convoluted the code. Current versions of IPC::Shareable do not allow data of arbitrary length. Each individual tied variable may not have a serialized length greater than the system's maximum shared memory segment size.
This version of IPC::Shareable does not understand the format of shared memory segments created versions prior to 0.60. If you try to tie to such segments, you will get an error. The only work around is to clear the shared memory segments and start with a fresh set.

The benefits afforded in terms of code simplication and performance on shorter segments more than make up for the above incompatibilities.

Documentation

The man page for IPC::Shareable is embedded in IPC::Shareable.pm. Copies of this document in various formats can be found in the doc directory of the distribution. In there will you find information about usage, pitfalls, etc.

Known Problems

Running out of semaphores

make test may fail with the message

Could not create semaphore set: No space left on device

This is because the test suite has used up all of the allowed number of semaphore sets and/or semaphores (SEMMNI and/or SEMMNS respectively). This seems to happen often on FreeBSD, where the default value is rather low. The only solution is to increase SEMMNI and/or SEMMNS for the system. Consult your system documentation for how to do this.

2. Running out of shared memory

make test may fail with the message

Munged shared memory segment (size exceeded?)

This is likely because the tests are exceeding the maximum size of a shared memory segment (SHMMAX) or the system-wide limit on shared memory size (SHMALL). The only solution is to increase SHMMAX and/or SHMALL for the system. Consult your system documentation for how to do this.

This failure could also mean that IPC::Shareable doesn't like your version of Storable (IPC::Shareable makes some assumptions about the structure of serialized data). This message would happen, for instance, when version 0.53 of IPC::Shareable was used in conjunction with 1.0.x versions of Storable. If you're having problems, try using Storable 1.0.7 which is known to work with IPC::Shareable 0.54.

3. Array operations on references

Generally, when a reference is assigned to a shared variable, the referenced data is also supposed to be shared. However, this currently is not the case for references assigned to an array via push(), splice(), and such. Suppose for example, you do

        @shared = ();
        push @shared, { %hv };

then the assignment

$shared->[0]->{foo} = "bar";

will not be shared with other processes since %hv is not shared. As a workaround you'll have to use array index operations:

        @shared = ();
        $shared[0] = { %hv };
        $shared->[0]->{foo} = "bar";

Note that push(), splice(), et al. work fine for non-references.

This bug will be fixed in a future release.

Etc

I have tested this on Linux only. YMMV may vary on other systems.

The two-year hiatus between releases of IPC::Shareable is symptomatic of the amount of time I have to contribute to this project. Help save the world! Submit me patches and improvements.

Also, don't be alarmed if I can't answer support emails. If this bothers you, you can always ask for your money back :-)

For a more light-weight, non-tie()-based interface to shared memory see Maurice Aubrey's IPC::ShareLite.

--
Ben Sugars (bsugars@canoe.ca)
March 5, 2001