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

cpanm Apache::SharedMem

perl -MCPAN -e shell
install Apache::SharedMem