view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    - constructor parameter 'cachename' is now optional, default value is 
      'default'
    - feature enhancements, new clear method and new constructor parameter 
      'default_lock_timeout'
    - major documentation update (it's now readable, and understandable)
    - new test scripts

0.04 Wed August 29 2001 09:42:00
    - major bugfix in "get" method: on first timeout, status was set to 
      "delete" method's status (often SUCCESS) instead of EXPIRED
    - bugfix in "set" method: wasn't unlock segment !
    - major bugfix in _check_key: use of max_keys parameter wasn't work 
      correctly

0.03 Mon Jully 30, 2001 13:43:01
    - fix major bug in "get" method: on unexists key, status was set to 
      SUCCESS insted of EXPIRED

0.02 Tue Junary 26, 2001 21:08:17
    - correct major bugs.

0.01 Mon Junary 25, 2001 07:43:48
    - original version writen from scratch.
    - fixing EXPORT_OK
    - fixing referencing bug in delete method

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 the
    Apache::SharedMem manpage 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 the Apache::SharedMem manpage 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.

    *   "default_expires_in" optional, date

        The default data expiration time for objects place in the cache.
        Integers is interpreted in seconds, constant EXPIRES_NOW make data
        expire imédiately and constant EXPIRES_NEVER make the data never
        expire. The timeout can also be in a human readable format, see the
        Time::ParseDate manpage for this format specification.

        Defaults to constant EXPIRES_NEVER if not explicitly set.

    *   "max_keys" optional, integer

        If you set more than "max_keys" keys, olders are automatically
        removed. Usefull to control the cache's grow. NOTE: if you know the
        exact length of your keys, use this option to control the cache size
        instead of the "max_size" option.

        Defaults to no max_keys

    *   "max_size" optional, integer

        no yet implemented

    *   "cachename" optional, string

        The namespace associated with this cache.