NAME

       Cache::Cache -- the Cache interface.

DESCRIPTION

       The Cache modules are designed to assist a developer in persisting data for a specified
       period of time.  Often these modules are used in web applications to store data locally to
       save repeated and redundant expensive calls to remote machines or databases.  People have
       also been known to use Cache::Cache for its straightforward interface in sharing data
       between runs of an application or invocations of a CGI-style script or simply as an easy
       to use abstraction of the filesystem or shared memory.

       The Cache::Cache interface is implemented by classes that support the get, set, remove,
       size, purge, and clear instance methods and their corresponding static methods for
       persisting data across method calls.

CACHE::CACHE VERSUS CHI

       Cache::Cache is in wide use and very stable, but has not changed in years and is no longer
       actively developed.

       CHI is the successor to Cache::Cache. It adheres to the basic Cache::Cache API but adds
       new features and drivers (e.g. FastMmap and Memcached), improves performance, and
       addresses limitations in the Cache::Cache implementation. The authors recommend the use of
       CHI going forward.

       Questions about Cache::Cache and CHI may be directed to the perl-cache mailing list at
       http://groups.google.com/group/perl-cache-discuss.

USAGE

       First, choose the best type of cache implementation for your needs.  The simplest cache is
       the MemoryCache, which is suitable for applications that are serving multiple sequential
       requests, and wish to avoid making redundant expensive queries, such as an Apache/mod_perl
       application talking to a database.  If you wish to share that data between processes, then
       perhaps the SharedMemoryCache is appropriate, although its behavior is tightly bound to
       the underlying IPC mechanism, which varies from system to system, and is unsuitable for
       large objects or large numbers of objects.  When the SharedMemoryCache is not acceptable,
       then FileCache offers all of the same functionality with similar performance metrics, and
       it is not limited in terms of the number of objects or their size.  If you wish to
       maintain a strict limit on the size of a file system based cache, then the
       SizeAwareFileCache is the way to go.  Similarly, the SizeAwareMemoryCache and the
       SizeAwareSharedMemoryCache add size management functionality to the MemoryCache and
       SharedMemoryCache classes respectively.

       Using a cache is simple.  Here is some sample code for instantiating and using a file
       system based cache.

         use Cache::FileCache;

         my $cache = new Cache::FileCache( );

         my $customer = $cache->get( $name );

         if ( not defined $customer )
         {
           $customer = get_customer_from_db( $name );
           $cache->set( $name, $customer, "10 minutes" );
         }

         return $customer;

CONSTANTS

       $EXPIRES_NEVER
           The item being set in the cache will never expire.

       $EXPIRES_NOW
           The item being set in the cache will expire immediately.

METHODS

       Clear( )
           Remove all objects from all caches of this type.

       Purge( )
           Remove all objects that have expired from all caches of this type.

       Size( )
           Returns the total size of all objects in all caches of this type.

       new( $options_hash_ref )
           Construct a new instance of a Cache::Cache. $options_hash_ref is a reference to a hash
           containing configuration options; see the section OPTIONS below.

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

       get( $key )
           Returns the data associated with $key.

       get_object( $key )
           Returns the underlying Cache::Object object used to store the cached data associated
           with $key.  This will not trigger a removal of the cached object even if the object
           has expired.

       purge(  )
           Remove all objects that have expired from the namespace associated with this cache
           instance.

       remove( $key )
           Delete the data associated with the $key from the cache.

       set( $key, $data, [$expires_in] )
           Associates $data with $key in the cache. $expires_in indicates the time in seconds
           until this data should be erased, or the constant $EXPIRES_NOW, or the constant
           $EXPIRES_NEVER.  Defaults to $EXPIRES_NEVER.  This variable can also be in the
           extended format of "[number] [unit]", e.g., "10 minutes".  The valid units are s,
           second, seconds, sec, m, minute, minutes, min, h, hour, hours, d, day, days, w, week,
           weeks, M, month, months, y, year, and years.  Additionally, $EXPIRES_NOW can be
           represented as "now" and $EXPIRES_NEVER can be represented as "never".

       set_object( $key, $object )
           Associates $key with Cache::Object $object.  Using set_object (as opposed to set) does
           not trigger an automatic removal of expired objects.

       size(  )
           Returns the total size of all objects in the namespace associated with this cache
           instance.

       get_namespaces( )
           Returns all the namespaces associated with this type of cache.

OPTIONS

       The options are set by passing in a reference to a hash containing any of the following
       keys:

       namespace
           The namespace associated with this cache.  Defaults to "Default" if not explicitly
           set.

       default_expires_in
           The default expiration time for objects place in the cache.  Defaults to
           $EXPIRES_NEVER if not explicitly set.

       auto_purge_interval
           Sets the auto purge interval.  If this option is set to a particular time ( in the
           same format as the expires_in ), then the purge( ) routine will be called during the
           first set after the interval expires.  The interval will then be reset.

       auto_purge_on_set
           If this option is true, then the auto purge interval routine will be checked on every
           set.

       auto_purge_on_get
           If this option is true, then the auto purge interval routine will be checked on every
           get.

PROPERTIES

       (get|set)_namespace( )
           The namespace of this cache instance

       get_default_expires_in( )
           The default expiration time for objects placed in this cache instance

       get_keys( )
           The list of keys specifying objects in the namespace associated with this cache
           instance

       get_identifiers( )
           This method has been deprecated in favor of get_keys( ).

       (get|set)_auto_purge_interval( )
           Accesses the auto purge interval.  If this option is set to a particular time ( in the
           same format as the expires_in ), then the purge( ) routine will be called during the
           first get after the interval expires.  The interval will then be reset.

       (get|set)_auto_purge_on_set( )
           If this property is true, then the auto purge interval routine will be checked on
           every set.

       (get|set)_auto_purge_on_get( )
           If this property is true, then the auto purge interval routine will be checked on
           every get.

SEE ALSO

       CHI - the successor to Cache::Cache

       Cache::Object, Cache::MemoryCache, Cache::FileCache, Cache::SharedMemoryCache, and
       Cache::SizeAwareFileCache

AUTHOR

       Original author: DeWitt Clinton <dewitt@unto.net>

       Last author:     $Author: dclinton $

       Copyright (C) 2001-2003 DeWitt Clinton