Olivier Poitrey > Apache-Cache-0.05 > Apache::Cache

Download:
Apache-Cache-0.05.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.05   Source  

NAME ^

Apache::Cache - Cache data accessible between Apache childrens

SYNOPSIS ^

    use Apache::Cache qw(:status);

    my $cache = new Apache::Cache(default_expires_in=>"5 minutes");

    # if the if the next line is called within 10 minutes, then this 
    # will return the cache value overwise, this will return undef and the
    # status method will be equal to the constant EXPIRED (exported by Apache::Cache
    # on demande via the :status tag)

    # the next line try to get the data from the cache, if the data is stored in
    # in the cache and if it not expired, then this return the data. Otherwise
    # if data have never been store in the cache, or if it's expired, this will
    # return undef and the status() method will be equal to constant EXPIRED (exported
    # by Apache::Cache on demand, via the :status tag)

    my $value = $cache->get('Key');

    if($cache->status eq EXPIRED)
    {
        # can't get the data from the cache, we will need to get it by the normal way
        # (via database, from file...)
        $value = get_my_data('Key'); # here, the get_my_data() function is a function of your
                                     # programe that generate a fresh value

        # this data have to expires in 30 secondes
        my $expires_in = '30 secondes';
        $cache->set(Key => $value, $expires_in);
    }
    elsif($cache->status eq FAILURE)
    {
        # don't use cache, cache maybe busy by another child or something goes wrong
        $value = get_my_data('Key');
    }

DESCRIPTION ^

This module allows you to cache data easily through shared memory. Whithin the framework of an apache/mod_perl use, this cache is accessible from any child process. The data validity is managed in the Cache::Cache model, but as well based on time than on size or number of keys.

Additionnally, you can implement a cache with Apache::Cache in your module without the risk of namespace clash because Apache::Cache is enclosed in the constructor's package's caller (see Apache::SharedMem for more details).

USAGE ^

For mod_perl users:

in your httpd.conf, put this directive:

    PerlAddVar PROJECT_DOCUMENT_ROOT /path/to/your/project/root/

and in your startup.pl:

    use Apache::Cache ();

See Apache::SharedMem for more details.

METHODS ^

new (cachename=> 'cachename', default_expires_in=> '1 second', max_keys=> 50, max_size=> 1_000)

Constuct a new Apache::Cache's instance.

Additionnaly, all Apache::SharedMem parameters are also customizable. See Apache::SharedMem.

set (identifier => data, [timeout])

    $cache->set(mykey=>'the data to cache', '15 minutes');
    if($cache->status & FAILURE)
    {
        warn("can't save data to cache: $cache->error");
    }

Store an item in the cache.

On failure this method return undef() and set status to FAILURE, see status() method below

status : FAILURE SUCCESS

get (identifier)

    my $value = $cache->get('Key');

    if($cache->status & (EXPIRED | FAILURE)) # if status is EXPIRED or FAILURE
    {
        $value = 'fresh value';
    }

Fetch the data specified. If data where never set, or if data have expired, this method return undef and status is set to EXPIRED.

status : FAILURE SUCCESS EXPIRED

delete (identifier)

Delete the data associated with the identifier from the cache.

status: SUCCESS FAILURE

clear

Remove all objects from the namespace associated with this cache instance.

status: SUCCESS FAILURE

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}

    # is last method failed or expired ?
    if($object->status & (FAILURE | EXPIRED)) {something to do on expired or 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::Cache qw(:status);

EXPORTS ^

Default exports

None.

Available exports

Following constant is available for exports : EXPIRED SUCCESS FAILURE EXPIRES_NOW EXPIRES_NEVER LOCK_EX LOCK_SH LOCK_UN.

Export tags defined

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

KNOW BUGS ^

Under mod_perl, with eavy load, this error may occured some time:

    Apache::SharedMem object initialization: Unable to initialize root ipc shared memory
    segment: File exists at /usr/local/lib/perl5/site_perl/5.005/Apache/SharedMem.pm line 929

We not really understand the probleme source, so any help will be appreciated. For fixing this problem when it occured, you should stop apache, clean the ipc segment and restart apache.

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::Cache needs Apache::SharedMem available from the CPAN.

SEE ALSO ^

Apache::SharedMem

HISTORY ^

$Log: Cache.pm,v $ Revision 1.24 2001/09/27 12:56:27 rs documentation upgrade

Revision 1.23 2001/09/24 08:18:20 rs status now return bitmask values

Revision 1.22 2001/09/21 16:24:13 rs new method clear new private methods _init_cache and _lock_timeout new constructor parameter 'default_lock_timeout'

Revision 1.21 2001/09/21 12:42:53 rs adding pod section KNOW BUGS

Revision 1.20 2001/09/20 12:40:18 rs Documentation update: add an EXPORTS section

Revision 1.19 2001/09/19 16:22:38 rs fixe a pod bug

Revision 1.18 2001/09/19 15:34:17 rs major doc update (METHOD section)

Revision 1.17 2001/09/19 13:37:43 rs 0.04 => 0.05

Revision 1.16 2001/09/19 13:37:09 rs - constructor have now a default value for "cachename", and the 'cachename' parameter is now optional

- Documentation upgrade (SINOPSYS simplified)

Revision 1.15 2001/08/29 07:45:32 rs add mod_perl specifique documentation

Revision 1.14 2001/08/28 13:22:46 rs major bugfix: _check_keys method wasn't clean keys correctly

Revision 1.13 2001/08/28 08:42:38 rs set method wasn't unlock on exit !

Revision 1.12 2001/08/17 13:26:36 rs some minor pod modifications

Revision 1.11 2001/08/17 13:20:45 rs - fix major bug in "get" method: on first timeout, status was set to "delete" method's status (often SUCCESS) instead of EXPIRED - add some sections to pod documentation

syntax highlighting: