NAME

VERSION

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 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

    use Storable qw( freeze thaw );
    ...
        $hash = { red => 1, white => 1, blue => 1 };
    $share->store( freeze( $hash ) );
    ...
    $hash = thaw( $share->fetch );

        $share->lock( LOCK_EX ); # same as default

        $share->lock( LOCK_SH );

        $share->lock( LOCK_EX|LOCK_NB );
        $share->lock( LOCK_SH|LOCK_NB );

        use IPC::ShareLite qw( :lock );

        $share->lock( LOCK_UN );

    my $num_writes = $share->version;

    my $key = $share->key;

    my $usage = $share->size * $share->num_segments;

PERFORMANCE

        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 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

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

See the Changes file for other contributors.

SEE ALSO