Olivier Poitrey > Apache-SharedMem-0.09 > Apache::SharedMem

Download:
Apache-SharedMem-0.09.tar.gz

Dependencies

Annotate this POD

Related Modules

IPC::Shareable
Data::Dumper
IPC::SysV
more...
By perlmonks.org

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 0.09   Source  

NAME ^

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

SYNOPSIS ^

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

    my $share = new Apache::SharedMem || die($Apache::SharedMem::ERROR);

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

    # ...maybe in another apache child
    my $var = $share->get(key);

    $share->delete(key);

    # delete all keys if the total size is larger than $max_size
    $share->clear if($share->size > $max_size);

    # using an exclusive blocking lock, but with a timeout
    my $lock_timeout = 40; # seconds
    if($share->lock(LOCK_EX, $lock_timeout))
    {
        my $data =...
        ...some traitement...
        
        $share->set(key => $data); # the implicite lock is not overrided
        warn('failed to store data in shared memory') if($share->status & 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 rootkey's generation.

You can also provide a PROJECT_ID, it's the server's uid by default. This value have to be numeric:

    PerlAddVar PROJECT_ID 10

METHODS ^

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

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

On succes return an Apache::SharedMem object, on error, return undef(). You can get error string via $Apache::SharedMem::ERROR.

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

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

Following status can be set (needs :status tag import):

SUCCESS FAILURE

On error, method return undef(), but undef() is also a valid answer, so don't test the method status by this way, use ($obj->status & SUCCESS) instead.

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

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

Try to set element key to value from the shared segment.

return 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]])

get a lock on the share segment. It returns undef() if failed, 1 if successed.

return status: FAILURE SUCCESS

unlock

freeing a lock

error

return the last error message that happened.

status

Return the last called method status. This status should be used with bitmask operators &, ^, ~ and | like this :

    # is last method failed ?
    if($object->status & FAILURE) {something to do on failure}

    # is last method don't succed ?
    if($object->status ^ SUCCESS) {something to do on failure}

It's not recommended to use equality operator (== and !=) or (eq and ne), they may don't work in future versions.

To import status' constants, you have to use the :status import tag, like below :

    use Apache::SharedMem qw(:status);

EXPORTS ^

Default exports

None.

Available exports

Following constant is available for exports : LOCK_EX LOCK_SH LOCK_UN LOCK_NB WAIT NOWAIT SUCCESS FAILURE

Export tags defined

The tag ":all" will get all of the above exports. Following tags are also available :

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

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.61 2001/10/04 12:15:22 rs Very major bugfix that made module unable to work correctly under mod_perl ! New version 0.09 to CPAN immediatly

Revision 1.60 2001/10/02 09:40:32 rs Bugfix in _get_rootkey private method: trap empty docroot or no read access to docroot error.

Revision 1.59 2001/09/24 08:19:40 rs status now return bitmask values

Revision 1.58 2001/09/21 14:45:30 rs little doc fixes

Revision 1.57 2001/09/21 12:43:41 rs Change copyright

Revision 1.56 2001/09/20 12:45:03 rs Documentation update: adding an EXPORTS section

Revision 1.55 2001/09/19 14:19:41 rs made a trace more verbose

Revision 1.54 2001/09/18 08:46:32 rs Documentation upgrade

Revision 1.53 2001/09/17 14:56:41 rs Suppression of ROOTKEYS global hash, obsolete. Documentation update: USAGE => PROJECT_ID

Revision 1.52 2001/08/29 15:54:01 rs little bug fix in _get_rootkey

Revision 1.51 2001/08/29 14:28:08 rs add warning on no existing document_root in _get_rootkey

Revision 1.50 2001/08/29 12:59:02 rs some documentation update. get method now return undef() if value is undefined.

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

syntax highlighting: