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 || die($Apache::SharedMem::ERROR);
$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 shared memory. This module internal functionment is much inspired from IPC::SharedCache, but without any cache management. The share memory segment key is automatically deduced by the caller package, which means that 2 modules can use same keys without being concerned about namespace clash. An additionnal namespace is used per application, which means that the same module, with the same namespace used in two applications doesn't clash too. Application distinction is made on two things : the process' UID and DOCUMENT_ROOT (for http applications) or current working directory.
This module handles all shared memory interaction via the IPC::SharedLite and all data serialization with Storable. See IPC::ShareLite and Storable for details.
USAGE
If you are running under mod_perl, you should put this line in your httpd.conf:
# must be a valid path
PerlAddVar PROJECT_DOCUMENT_ROOT /path/to/your/projects/root
and in your startup.pl:
use Apache::SharedMem;
This allow Apache::SharedMem to determine a unique rootkey for all virtual hosts, and to cleanup this rootkey on Apache stop. PROJECT_DOCUMENT_ROOT is used instead of a per virtal host's DOCUMENT_ROOT for generating the rootkey.
METHODS
new (namespace => 'Namespace', ipc_mode => 0666, ipc_segment_size => 1_000, debug => 1)
rootkey
(optional) integer:
Changes the root segment key. It must be an unsigned integer. Don't use this option unless you really know what you are doing.
This key allows Apache::SharedMem to find the root map of all namespaces (see below) owned by your application.
The rootkey is automatically generated using the ftok
provided by IPC::SysV. Process' UID and DOCUMENT_ROOT (or current working directory) are given to ftok
so as to guarantee an unique key as far as possible.
Note, if you are using mod_perl, and you'v load mod_perl via startup.pl (see USAGE section for more details), the rootkey is generated once at the apache start, based on the supplied PROJECT_DOCUMENT_ROOT and Apache's uid.
namespace
(optional) string:
Setup manually the namespace. To share same datas, your program must use the same namespace. This namespace is set by default to the caller's package name. In most cases the default value is a good choice. But you may setup manually this value if, for example, you want to share the same datas between two or more modules.
ipc_mode
(optional) octal:
Setup manually the segment mode (see IPC::ShareLite) for more details (default: 0600). Warning: this value _must_ be octal, see chmod documentation in perlfunc manpage for more details.
ipc_segment_size
(optional) integer:
Setup manually the segment size (see IPC::ShareLite) for more details (default: 65_536).
debug
(optional) boolean:
Turn on/off the debug mode (default: 0)
In most case, you don't need to give any arguments to the constructor.
ipc_mode
and ipc_segment_size
are used only on the first namespace initialisation. Using different values on an existing key (in shared memory) has no effect.
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) string:
This is the name of elemenet that you want get from the shared namespace. It can be any string that perl support for hash's key.
wait (optional):
Defined the locking status of the request. If you must get the value, and can't continue without it, set this argument to constant WAIT, unless you can set it to NOWAIT.
If the key is locked when you are tring to get the value, NOWAIT return status FAILURE, and WAIT hangup until the value is unlocked. An alternative is to setup a WAIT timeout, see below.
NOTE: you needs :wait tag import:
use Apache::SharedMem qw(:wait)
timeout (optional) integer:
if WAIT is on, timeout setup the number of seconds to wait for a blocking lock, usefull for preventing dead locks.
Following status can be set:
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 [namespace]
Release share memory space taken by the given namespace or object's namespace. Root map will be release too if empty.
destroy
Destroy all namespace found in the root map, and root map itself.
size ([wait, [timeout]])
namespaces
Debug method, return the list of all namespace in the root map. (devel only)
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 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, shmget, ftok
HISTORY
$Log: SharedMem.pm,v $ Revision 1.49 2001/08/29 08:30:32 rs syntax bugfix
Revision 1.48 2001/08/29 08:27:13 rs doc fix
Revision 1.47 2001/08/29 08:24:23 rs meny documentation updates
Revision 1.46 2001/08/28 16:42:14 rs adding better support of mod_perl with a cleanup method handled to Apache's registry_cleanup.
Revision 1.45 2001/08/28 10:17:00 rs little documentation fix
Revision 1.44 2001/08/28 08:45:12 rs stop using autouse for Data::Dumper, mod_perl don't like it add auto unlock on DESTROY, seem to work under mod_perl with Apache::Registry TODO test with mod_perl handlers
Revision 1.43 2001/08/27 15:42:02 rs bugfix in release method, on root map cleanup, ipc_mode must be defined bugfix in _init_namespace method, if object was create without any "set" called, the empty namespace won't be allocated.
Revision 1.42 2001/08/24 16:11:25 rs - Implement a more efficient IPC key generation for the root segment, using the system ftok() function provied by IPC::SysV module - Pod documentation - Default IPC mode is now 0600 - We now keep ipc_mode and ipc_segment_size in the root map for calling IPC::ShareLite with same values. - Add "readonly" parameter to constructor - Feature enhancement, add "dump" and "dump_map" methods - Data::Dumper is now autoused - Feature enhancement, release method now release root map when it go empty - Feature enhancement, add a "destroy" method, that call "release" method on all root-map's namespaces. Usefull for cleaning shared memory on Apache shutdown. - Misc bugfixes
Revision 1.41 2001/08/23 08:37:03 rs major bug, _get_rootkey was call mod_perl method on a wrong object
Revision 1.40 2001/08/23 08:08:18 rs little documentation update
Revision 1.39 2001/08/23 00:56:32 rs vocabulary correction in POD documentation
Revision 1.38 2001/08/22 16:10:15 rs - Pod documentation - Default IPC mode is now 0600 - We now keep ipc_mode and ipc_segment_size in the root map for calling IPC::ShareLite with same values. - Bugfix, release now really clean segments (seem to be an IPC::ShareLite bug)
Revision 1.37 2001/08/21 13:17:35 rs switch to version O.07
Revision 1.36 2001/08/21 13:17:02 rs add method _get_rootkey. this method allow constructor to determine a more uniq ipc key. key is generated with IPC::SysV::ftok() function, based on ducument_root and user id.
Revision 1.35 2001/08/17 13:28:18 rs make precedence more readable in "_set_status" method some pod corrections
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
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 230:
Non-ASCII character seen before =encoding in ''mykey´:'. Assuming CP1252