NAME¶
IPC::ShareLite - Lightweight interface to shared memory
VERSION¶
This document describes IPC::ShareLite version 0.17
SYNOPSIS¶
use IPC::ShareLite;
my $share = IPC::ShareLite->new(
-key => 1971,
-create => 'yes',
-destroy => 'no'
) or die $!;
$share->store( "This is stored in shared memory" );
my $str = $share->fetch;
DESCRIPTION¶
IPC::ShareLite provides a simple interface to shared memory, allowing data to be
efficiently communicated between processes. Your operating system must support
SysV IPC (shared memory and semaphores) in order to use this module.
IPC::ShareLite provides an abstraction of the shared memory and semaphore
facilities of SysV IPC, allowing the storage of arbitrarily large data; the
module automatically acquires and removes shared memory segments as needed.
Storage and retrieval of data is atomic, and locking functions are provided
for higher-level synchronization.
In many respects, this module is similar to IPC::Shareable. However,
IPC::ShareLite does not provide a tied interface, does not (automatically)
allow the storage of variables, and is written in C for additional speed.
Construct an IPC::ShareLite object by calling its constructor:
my $share = IPC::ShareLite->new(
-key => 1971,
-create => 'yes',
-destroy => 'no'
) or die $!;
Once an instance has been created, data can be written to shared memory by
calling the
store() method:
$share->store("This is going in shared memory");
Retrieve the data by calling the
fetch() method:
my $str = $share->fetch();
The
store() and
fetch() methods are atomic; any processes
attempting to read or write to the memory are blocked until these calls
finish. However, in certain situations, you'll want to perform multiple
operations atomically. Advisory locking methods are available for this
purpose.
An exclusive lock is obtained by calling the
lock() method:
$share->lock();
Happily, the
lock() method also accepts all of the flags recognized by
the
flock() system call. So, for example, you can obtain a shared lock
like this:
$share->lock( LOCK_SH );
Or, you can make either type of lock non-blocking:
$share->lock( LOCK_EX|LOCK_NB );
Release the lock by calling the
unlock() method:
$share->unlock;
METHODS¶
"new($key, $create, $destroy, $exclusive, $mode, $flags, $size)"¶
This is the constructor for IPC::ShareLite. It accepts both the positional and
named parameter calling styles.
$key is an integer value used to associate data between processes. All processes
wishing to communicate should use the same $key value. $key may also be
specified as a four character string, in which case it will be converted to an
integer value automatically. If $key is undefined, the shared memory will not
be accessible from other processes.
$create specifies whether the shared memory segment should be created if it does
not already exist. Acceptable values are 1, 'yes', 0, or 'no'.
$destroy indicates whether the shared memory segments and semaphores should be
removed from the system once the object is destroyed. Acceptable values are 1,
'yes', 0, or 'no'.
If $exclusive is true, instantiation will fail if the shared memory segment
already exists. Acceptable values are 1, 'yes', 0, or 'no'.
$mode specifies the permissions for the shared memory and semaphores. The
default value is 0666.
$flags specifies the exact shared memory and semaphore flags to use. The
constants IPC_CREAT, IPC_EXCL, and IPC_PRIVATE are available for import.
$size specifies the shared memory segment size, in bytes. The default size is
65,536 bytes, which is fairly portable. Linux, as an example, supports segment
sizes of 4 megabytes.
The constructor croaks on error.
"store( $scalar )"¶
This method stores $scalar into shared memory. $scalar may be arbitrarily long.
Shared memory segments are acquired and released automatically as the data
length changes. The only limits on the amount of data are the system-wide
limits on shared memory pages (SHMALL) and segments (SHMMNI) as compiled into
the kernel.
The method raises an exception on error.
Note that unlike IPC::Shareable, this module does not automatically allow
references to be stored. Serializing all data is expensive, and is not always
necessary. If you need to store a reference, you should employ the Storable
module yourself. For example:
use Storable qw( freeze thaw );
...
$hash = { red => 1, white => 1, blue => 1 };
$share->store( freeze( $hash ) );
...
$hash = thaw( $share->fetch );
"fetch"¶
This method returns the data that was previously stored in shared memory. The
empty string is returned if no data was previously stored.
The method raises an exception on error.
"lock( $type )"¶
Obtains a lock on the shared memory. $type specifies the type of lock to
acquire. If $type is not specified, an exclusive read/write lock is obtained.
Acceptable values for $type are the same as for the
flock() system
call. The method returns true on success, and undef on error. For non-blocking
calls (see below), the method returns 0 if it would have blocked.
Obtain an exclusive lock like this:
$share->lock( LOCK_EX ); # same as default
Only one process can hold an exclusive lock on the shared memory at a given
time.
Obtain a shared lock this this:
$share->lock( LOCK_SH );
Multiple processes can hold a shared lock at a given time. If a process attempts
to obtain an exclusive lock while one or more processes hold shared locks, it
will be blocked until they have all finished.
Either of the locks may be specified as non-blocking:
$share->lock( LOCK_EX|LOCK_NB );
$share->lock( LOCK_SH|LOCK_NB );
A non-blocking lock request will return 0 if it would have had to wait to obtain
the lock.
Note that these locks are advisory (just like flock), meaning that all
cooperating processes must coordinate their accesses to shared memory using
these calls in order for locking to work. See the
flock() call for
details.
Locks are inherited through forks, which means that two processes actually can
possess an exclusive lock at the same time. Don't do that.
The constants LOCK_EX, LOCK_SH, LOCK_NB, and LOCK_UN are available for import:
use IPC::ShareLite qw( :lock );
Or, just use the flock constants available in the Fcntl module.
"unlock"¶
Releases any locks. This is actually equivalent to:
$share->lock( LOCK_UN );
The method returns true on success and undef on error.
"version"¶
Each share has a version number that incrementents monotonically for each write
to the share. When the share is initally created its version number will be 1.
my $num_writes = $share->version;
"key"¶
Get a share's key.
my $key = $share->key;
"create"¶
Get a share's create flag.
"exclusive"¶
Get a share's exclusive flag.
"flags"¶
Get a share's flag.
"mode"¶
Get a share's mode.
"size"¶
Get a share's segment size.
"num_segments"¶
Get the number of segments in a share. The memory usage of a share can be
approximated like this:
my $usage = $share->size * $share->num_segments;
$usage will be the memory usage rounded up to the next segment boundary.
"destroy"¶
Get or set the share's destroy flag.
For a rough idea of the performance you can expect, here are some benchmarks.
The tests were performed using the Benchmark module on a Cyrix PR166+ running
RedHat Linux 5.2 with the 2.0.36 kernel, perl 5.005_02 using perl's malloc,
and the default shared memory segment size. Each test was run 5000 times.
DATA SIZE (bytes) TIME (seconds) Op/Sec
store 16384 2 2500
fetch 16384 2 2500
store 32768 3 1666
fetch 32768 3 1666
store 65536 6 833
fetch 65536 5 1000
store 131072 12 416
fetch 131072 12 416
store 262144 28 178
fetch 262144 27 185
store 524288 63 79
fetch 524288 61 81
Most of the time appears to be due to memory copying. Suggestions for speed
improvements are welcome.
PORTABILITY¶
The module should compile on any system with SysV IPC and an ANSI C compiler,
and should compile cleanly with the -pedantic and -Wall flags.
The module has been tested under Solaris, FreeBSD, and Linux. Testing on other
platforms is needed.
If you encounter a compilation error due to the definition of the semun union,
edit the top of sharestuff.c and undefine the semun definition. And then
please tell me about it.
I've heard rumors that a SysV IPC interface has been constructed for Win32
systems. Support for it may be added to this module.
IPC::ShareLite does not understand the shared memory data format used by
IPC::Shareable.
AUTHOR¶
Copyright 1998-2002, Maurice Aubrey <maurice@hevanet.com>. All rights
reserved.
This release by Andy Armstrong <andy@hexten.net>.
This module is free software; you may redistribute it and/or modify it under the
same terms as Perl itself.
CREDITS¶
Special thanks to Benjamin Sugars for developing the IPC::Shareable module.
See the Changes file for other contributors.
SEE ALSO¶
IPC::Shareable,
ipc(2),
shmget(2),
semget(2), perl.