Provided by: libfile-cache-perl_0.16-18_all bug

NAME

       File::Cache - Share data between processes via filesystem

NOTE

       Use of File::Cache is now discouraged in favor of the new Cache::Cache project, also
       available on CPAN.  Cache::Cache offers all of the functionality of File::Cache, as well
       as integrating the functionality of IPC::Cache and a number of new features.  You can view
       the Cache::Cache project page at:

         http://sourceforge.net/projects/perl-cache/

DESCRIPTION

       File::Cache is a perl module that implements an object storage space where data is
       persisted across process boundaries via the filesystem.

       File::Cache builds a cache in the file system using a multi-level directory structure that
       looks like this:

         <CACHE_KEY>/<USERNAME>/<NAMESPACE>/[D1]/[D2]/.../<OBJECTS>

       CACHE_KEY is the location of the root level of the cache. The cache key defaults to
       <TMPDIR>/File::Cache, where <TMPDIR> is the temporary directory on your system. USERNAME
       is the user identifier. This value defaults to the userid, if it can be determined from
       the system, or "nobody" if it can not. <NAMESPACE> defaults to "_default". D1, D2, etc.
       are subdirectories that are created to hold the cache objects.  The number subdirectories
       depends on the cache_depth value, which defaults to 0. Objects are stored in the cache
       using a method which depends on the persistence_mechanism value.

SYNOPSIS

        use File::Cache;

        # create a cache in the default namespace, where objects
        # do not expire

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

        # create a user-private cache in the specified
        # namespace, where objects will expire in one day, and
        # will automatically be removed from the cache.

        my $cache = new File::Cache( { namespace  => 'MyCache',
                                       expires_in => 86400,
                                       filemode => 0600 } );

        # create a public cache in the specified namespace,
        # where objects will expire in one day, but will not be
        # removed from the cache automatically.

        my $cache = new File::Cache( { namespace  => 'MyCache',
                                       expires_in => 86400,
                                       username => 'shared_user',
                                       auto_remove_stale => 0,
                                       filemode => 0666 } );

        # create a cache readable by the user and the user's
        # group in the specified namespace, where objects will
        # expire in one day, but may be removed from the cache
        # earlier if the size becomes more than a megabyte. Also,
        # request that the cache use subdirectories to increase
        # performance of large number of objects

        my $cache = new File::Cache( { namespace  => 'MyCache',
                                       expires_in => 86400,
                                       max_size => 1048576,
                                       username => 'shared_user',
                                       filemode => 0660,
                                       cache_depth => 3 } );

        # store a value in the cache (will expire in one day)

        $cache->set("key1", "value1");

        # retrieve a value from the cache

        $cache->get("key1");

        # retrieve a stale value from the cache.
        # (Undefined behavior if auto_remove_stale is 1)

        $cache->get_stale("key1");

        # store a value that expires in one hour

        $cache->set("key2", "value2", 3600);

        # reduce the cache size to 3600 bytes

        $cache->reduce_size(3600);

        # clear this cache's contents

        $cache->clear();

        # delete all namespaces from the filesystem

        File::Cache::CLEAR();

   TYPICAL USAGE
       A typical scenario for this would be a mod_perl or perl CGI application.  In a multi-tier
       architecture, it is likely that a trip from the front-end to the database is the most
       expensive operation, and that data may not change frequently.  Using this module will help
       keep that data on the front-end.

       Consider the following usage in a mod_perl application, where a mod_perl application
       serves out images that are retrieved from a database.  Those images change infrequently,
       but we want to check them once an hour, just in case.

       my $imageCache = new Cache( { namespace => 'Images',
                                     expires_in => 3600 } );

       my $image = $imageCache->get("the_requested_image");

       if (!$image) {

           # $image = [expensive database call to get the image]

           $imageCache->set("the_requested_image", $image);

       }

       That bit of code, executed in any instance of the mod_perl/httpd process will first try
       the filesystem cache, and only perform the expensive database call if the image has not
       been fetched before, has timed out, or the cache has been cleared.

       The current implementation of this module automatically removes expired items from the
       cache when the get() method is called and the auto_remove_stale setting is true.
       Automatic removal does not occur when the set() method is called, which means that the
       cache can become polluted with expired items if many items are stored in the cache for
       short periods of time, and are rarely accessed. This is a design decision that favors
       efficiency in the common case, where items are accessed frequently. If you want to limit
       cache growth, see the max_size option, which will automatically shrink the cache when the
       set() method is called. (max_size is unaffected by the value of auto_remove_stale.)

       Be careful that you call the purge method periodically if auto_remove_stale is 0 and
       max_size has its default value of unlimited size. In this configuration, the cache size
       will be a function of the number of items inserted into the cache since the last purge.
       (i.e. It can grow extremely large if you put lots of different items in the cache.)

   METHODS
       new(\%options)
           Creates a new instance of the cache object.  The constructor takes a reference to an
           options hash which can contain any or all of the following:

           $options{namespace}
               Namespaces provide isolation between objects.  Each cache refers to one and only
               one namespace.  Multiple caches can refer to the same namespace, however.  While
               specifying a namespace is not required, it is recommended so as not to have data
               collide.

           $options{expires_in}
               If the "expires_in" option is set, all objects in this cache will be cleared in
               that number of seconds.  It can be overridden on a per-object basis.  If
               expires_in is not set, the objects will never expire unless explicitly set.

           $options{cache_key}
               The "cache_key" is used to determine the underlying filesystem namespace to use.
               In typical usage, leaving this unset and relying on namespaces alone will be more
               than adequate.

           $options{username}
               The "username" is used to explicitely set the username. This is useful for cases
               where one wishes to share a cache among multiple users. If left unset, the value
               will be the current user's username. (Also see $options{filemode}.)  Note that the
               username is not used to set ownership of the cache files -- the i.e. the username
               does not have to be a user of the system.

           $options{filemode}
               "filemode" specifies the permissions for cache files. This is useful for cases
               where one wishes to share a cache among multiple users. If left unset, the value
               will be "u", indicating that only the current user can read an write the cache
               files. See the filemode() method documentation for the specification syntax.

           $options{max_size}
               "max_size" specifies the maximum size of the cache, in bytes.  Cache objects are
               removed during the set() operation in order to reduce the cache size before the
               new cache value is added. See the reduce_size() documentation for the cache object
               removal policy. The max_size will be maintained regardless of the value of
               auto_remove_stale. The default is $File::Cache::sNO_MAX_SIZE, which indicates that
               the cache has no maximum size.

           $options(auto_remove_stale}
               "auto_remove_stale" specifies that the cache should remove expired objects from
               the cache when they are requested.

           $options(cache_depth}
               "cache_depth" specifies the depth of the subdirectories that should be created.
               This is helpful when especially large numbers of objects are being cached (>1000)
               at once.  The optimal number of files per directory is dependent on the type of
               filesystem, so some hand-tuning may be required.

       set($identifier, $object, $expires_in)
           Adds an object to the cache.  set takes the following parameters:

           $identifier
               The key the refers to this object.

           $object
               The object to be stored.  This any Storable or Data::Dumper-able scalar or
               (optionally blessed) ref.  Filehandles and database handles can not be stored, but
               most other references to objects can be.

           $expires_in (optional)
               The object will be cleared from the cache in this number of seconds.  Overrides
               the default expires_in value for the cache.

       get($identifier)
           get retrieves an object from the cache.  If the object referred to by the identifier
           exists in the cache and has not expired then then object will be returned.  If the
           object does not exist then get will return undef.  If the object does exist but has
           expired then get will return undef and, depending on the setting of auto_remove_stale,
           remove the expired object from the cache.

           $identifier
               The key referring to the object to be retrieved.

       get_stale($identifier)
           get_stale retrieves objects that have expired from the cache.  Normally, expired
           objects are removed automatically and can not be retrieved via get_stale, but if the
           auto_remove_stale option is set to false, then expired objects will be left in the
           cache.  get_stale returns undef if the object does not exist at all or has not expired
           yet.

           $identifier
               The key referring to the object to be retrieved.

       remove($identifier)
           Removes an object from the cache.

           $identifier
               The key referring to the object to be removed.

       clear()
           Removes all objects from this cache.

       purge()
           Removes all objects that have expired

       size()
           Return an estimate of the disk usage of the current namespace.

       reduce_size($size)
           Reduces the size of the cache so that it is below $size. Note that the cache size is
           approximate, and may slightly exceed the value of $size.

           Cache objects are removed in order of nearest expiration time, or latest access time
           if there are no cache objects with expiration times. (If there are a mix of cache
           objects with expiration times and without, the ones with expiration times are removed
           first.)  reduce_size takes the following parameter:

           $size
               The new target cache size.

       get_creation_time($identifier)
           Gets the time at which the data associated with $identifier was stored in the cache.
           Returns undef if $identifier is not cached.

           $identifier
               The key referring to the object to be retrieved.

       get_expiration_time($identifier)
           Gets the time at which the data associated with $identifier will expire from the
           cache. Returns undef if $identifier is not cached.

           $identifier
               The key referring to the object to be retrieved.

       get_global_expires_in()
           Returns the default number of seconds before an object in the cache expires.

       set_global_expires_in($global_expires_in)
           Sets the default number of seconds before an object in the cache expires.
           set_global_expires_in takes the following parameter:

           $global_expires_in
               The default number of seconds before an object in the cache expires.  It should be
               a number greater than zero, $File::Cache::sEXPIRES_NEVER, or
               $File::Cache::sEXPIRES_NOW.

       get_auto_remove_stale()
           Returns whether or not the cache will automatically remove objects after they expire.

       set_auto_remove_stale($auto_remove_stale)
           Sets whether or not the cache will automatically remove objects after they expire.
           set_auto_remove_stale takes the following parameter:

           $auto_remove_stale
               The new auto_remove_stale value.  If $auto_remove_stale is 1 or
               $File::Cache::sTRUE, then the cache will automatically remove items when they are
               being retrieved if they have expired.  If $auto_remove_stale is 0 or
               $File::Cache::sFALSE, the cache will only remove expired items when the purge()
               method is called, or if max_size is set.  Note that the behavior of get_stale is
               undefined if $auto_remove_stale is true.

       get_username()
           Returns the username that is currently being used to define the location of this
           cache.

       set_username($username)
           Sets the username that is currently being used to define the location of this cache.
           set_username takes the following parameter:

           $username
               The username that is to be used to define the location of this cache. It is not
               directly used to determine the ownership of the cache files, but can be used to
               isolate sections of a cache for different permissions.

       get_namespace()
           Returns the current cache namespace.

       set_namespace($namespace)
           Sets the cache namespace. set_namespace takes the following parameter:

           $namespace
               The namespace that is to be used by the cache. The namespace can be used to
               isolate sections of a cache.

       get_max_size()
           Returns the current cache maximum size. $File::Cache::sNO_MAX_SIZE (the default)
           indicates no maximum size.

       set_max_size($max_size)
           Sets the maximum cache size. The cache size is reduced as necessary.  set_max_size
           takes the following parameter:

           $max_size
               The maximum size of the cache. $File::Cache::sNO_MAX_SIZE indicates no maximum
               size.

       get_cache_depth()
           Returns the current cache depth.

       set_cache_depth($cache_depth)
           Sets the cache depth. Consider calling clear() before resetting the cache depth in
           order to prevent inaccessible cache objects from occupying disk space. set_cache_depth
           takes the following parameter:

           $cache_depth
               The depth of subdirectories that are to be used by the cache when storing cache
               objects.

       get_persistence_mechanism()
           Returns the current cache persistence mechanism.

       set_persistence_mechanism($persistence_mechanism)
           Sets the cache persistence mechanism. This method clears the cache in order to ensure
           consistent cache objects. set_persistence_mechanism takes the following parameter:

           $persistence_mechanism
               The persistence mechanism that is to be used by the cache. This value can be
               either "Storable" or "Data::Dumper".

       get_filemode()
           Returns the filemode specification for newly created cache objects.

       set_filemode($mode)
           Sets the filemode specification for newly created cache objects.  set_filemode takes
           the following parameter:

           $mode
               The file mode -- a numerical mode identical to that used by chmod(). See the
               chmod() documentation for more information.

       File::Cache::CLEAR($cache_key)
           Removes this cache and all the associated namespaces from the filesystem.  CLEAR takes
           the following parameter:

           $cache_key (optional)
               Specifies the filesystem data to be cleared.  Needed only if a cache was created
               with a non-standard cache key.

       File::Cache::PURGE($cache_key)
           Removes all objects in all namespaces that have expired.  PURGE takes the following
           parameter:

           $cache_key (optional)
               Specifies the filesystem data to be purged.  Needed only if a cache was created
               with a non-standard cache key.

       File::Cache::SIZE($cache_key)
           Roughly estimates the amount of memory in use.  SIZE takes the following parameter:

           $cache_key (optional)
               Specifies the filesystem data to be examined.  Needed only if a cache was created
               with a non-standard cache key.

       File::Cache::REDUCE_SIZE($size, $cache_key)
           Reduces the size of the cache so that it is below $size. Note that the cache size is
           approximate, and may slightly exceed the value of $size.

           Cache objects are removed in order of nearest expiration time, or latest access time
           if there are no cache objects with expiration times. (If there are a mix of cache
           objects with expiration times and without, the ones with expiration times are removed
           first.)  REDUCE_SIZE takes the following parameters:

           $size
               The new target cache size.

           $cache_key (optional)
               Specifies the filesystem data to be examined.  Needed only if a cache was created
               with a non-standard cache key.

BUGS

       •   The root of the cache namespace is created with global read/write permissions.

SEE ALSO

       IPC::Cache, Storable, Data::Dumper

AUTHOR

       DeWitt Clinton <dewitt@unto.net>, and please see the CREDITS file