view release on metacpan or  search on metacpan

lib/Apache/Cache.pm  view on Meta::CPAN

package Apache::Cache;
#$Id: Cache.pm,v 1.24 2001/09/27 12:56:27 rs Exp $

=pod

=head1 NAME

Apache::Cache - Cache data accessible between Apache childrens

=head1 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');
    }

=head1 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 L<Apache::SharedMem> for more details).

=head1 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 L<Apache::SharedMem> for more details.

=cut

BEGIN
{
    use strict;
    use 5.005;
    use Carp;
    use Apache::SharedMem qw(:all);
    use Time::ParseDate;

    use base qw(Apache::SharedMem Exporter);

    %Apache::Cache::EXPORT_TAGS = 
    (
        all       => [qw(EXPIRED SUCCESS FAILURE EXPIRES_NOW EXPIRES_NEVER LOCK_EX LOCK_SH LOCK_UN LOCK_NB)],
        expires   => [qw(EXPIRES_NOW EXPIRES_NEVER)],
        status    => [qw(SUCCESS FAILURE EXPIRED)],
        lock      => [qw(LOCK_EX LOCK_SH LOCK_UN LOCK_NB)],
    );
    @Apache::Cache::EXPORT_OK   = @{$Apache::Cache::EXPORT_TAGS{'all'}};

    # SUCCESS => 1
    # FAILURE => 2
    use constant EXPIRED        => 4;

    use constant EXPIRES_NOW    => 1;
    use constant EXPIRES_NEVER  => 0;

    $Apache::Cache::VERSION     = '0.05';
}

=pod