The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Apache::SharedMem - Share data between Apache children prcesses through the shared memory

SYNOPSIS

    use Apache::SharedMem qw(:lock :wait :status);

    my $share = new Apache::SharedMem;

    $share->set(key=>'some data');

    # ...in another process
    my $var = $share->get(key, NOWAIT);
    die("can't get key: ", $self->error) unless($share->status eq SUCCESS);

    $share->delete(key);

    $share->clear if($share->size > $max_size);

    my $lock_timeout = 40; # seconds
    if($share->lock(LOCK_EX, $lock_timeout))
    {
        my $data...
        ...some traitement...
        $share->set(key=>$data);
        warn(...) if($share->status eq FAILURE);
        $share->unlock;
    }
    
    $share->release;

DESCRIPTION

This module make it easier to share data between Apache children processes trough the shared memory. This module internal working is a lot inspired by IPC::SharedCache, but without any cache managment. The share memory segment key is automatically deduced by the caller package, that's mine 2 modules can use same keys without be concerned about namespace clash.

This module handles all shared memory interaction use the IPC::SharedLite module and all data serialization using Storable. See IPC::ShareLite and Storable for details.

USAGE

in construction

METHODS

new (namespace => 'Namespace', ipc_mode => 0666, ipc_segment_size => 1_000, debug => 1)

rootname (optional): change the default root name segment identifier (default: TOOR).

namespace (optional): setup manually the package name (default: caller package name).

ipc_mode (optional): setup manually segment mode (see IPC::ShareLite man page) (default: 0666).

ipc_segment_size (optional): setup manually segment size (see IPC::ShareLite man page) (default: 65_536).

debug (optional): turn on/off debug mode (default: 0)

In most case, you don't need to give any arguments to the constructor. But for some resons, (like share the same namespace between 2 modules) you can setup some parameters manually.

Note that ipc_segment_size is

get (key, [wait, [timeout]])

my $var = $object->get('mykey', WAIT, 50); if($object->status eq FAILURE) { die("can't get key 'mykey´: " . $object->error); }

key (required): key to get from shared memory

wait (optional): WAIT or NOWAIT (default WAIT) make or not a blocking shared lock (need :wait tag import).

timeout (optional): if WAIT is on, timeout setup the number of seconds to wait for a blocking lock (usefull for preventing dead locks)

Try to get element key from the shared segment. On failure, this methode return undef() and set status to FAILURE.

status: SUCCESS FAILURE

set (key, value, [wait, [timeout]])

my $rv = $object->set('mykey' => 'somevalue'); if($object->status eq FAILURE) { die("can't set key 'mykey´: " . $object->error); }

key (required): key to set

value (required): value a store in key

wait (optional): WAIT or NOWAIT (default WAIT) make or not a blocking shared lock (need :wait tag import).

timeout (optional): if WAIT is on, timeout setup the number of seconds to wait for a blocking lock (usefull for preventing dead locks)

Try to set element key to value from the shared segment. On failure, this methode return undef().

status: SUCCESS FAILURE

delete (key, [wait, [timeout]])

exists (key, [wait, [timeout]])

firstkey ([wait, [timeout]])

nextkey (lastkey, [wait, [timeout]])

clear ([wait, [timeout]])

return 0 on error

release

size ([wait, [timeout]])

lock ([lock_type, [timeout]])

lock_type (optional): type of lock (LOCK_EX, LOCK_SH, LOCK_NB, LOCK_UN)

timeout (optional): time to wait for an exclusive lock before aborting

get a lock on the root share segment. return undef on failure, 1 on success.

unlock

freeing a lock

error

return the last happened error message.

AUTHOR

Olivier Poitrey <rs@rhapsodyk.net>

LICENCE

This program 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 program 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 the program; if not, write to the Free Software Foundation, Inc. :

59 Temple Place, Suite 330, Boston, MA 02111-1307

COPYRIGHT

Copyright (C) 2001 - Fininfo http://www.fininfo.fr

HISTORY

$Log: SharedMem.pm,v $ Revision 1.28 2001/07/03 14:53:02 rs make a real changes log

1 POD Error

The following errors were encountered while parsing the POD:

Around line 154:

Non-ASCII character seen before =encoding in ''mykey´:'. Assuming CP1252