phpman > perldoc > IPC::ShareLite(3pm)

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.

PERFORMANCE
    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 AT hevanet.com>. All rights reserved.

    This release by Andy Armstrong <andy AT 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.