NAME

Apache::SharedMem - Share data between Apache children processes 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 through the shared memory. This module internal functionment is a lot inspired from IPC::SharedCache, but without any cache managment. The share memory segment key is automatically deduced by the caller package, that's means 2 modules can use same keys without being 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

under 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 the segment mode (see IPC::ShareLite man page) (default: 0666).

ipc_segment_size (optional): setup manually the 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 reasons, (like, for example, sharing the same namespace between 2 modules) you can setup some parameters manually.

Note that ipc_segment_size is default value of IPC::ShareLite, see IPC::ShareLite

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 an element key from the shared segment. In case of failure, this methode returns 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): store a value 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. In case of 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. It returns undef() if failed, 1 if successed.

unlock

freeing a lock

error

return the last error message that happened.

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

PREREQUISITES

Apache::SharedMem needs IPC::ShareLite, Storable both available from the CPAN.

SEE ALSO

IPC::ShareLite, IPC::SharedMem, shmget

HISTORY

$Log: SharedMem.pm,v $ Revision 1.34 2001/08/08 14:15:07 rs forcing default lock to LOCK_EX

Revision 1.33 2001/08/08 14:01:45 rs grrr syntax error second part, it's not my day.

Revision 1.32 2001/08/08 13:59:01 rs syntax error introdius with the last fix

Revision 1.31 2001/08/08 13:56:35 rs Starting version 0.06 fixing an "undefined value" bug in lock methode

Revision 1.30 2001/07/04 08:41:11 rs major documentation corrections

Revision 1.29 2001/07/03 15:24:19 rs fix doc

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