NAME

       Cache::File - Filesystem based implementation of the Cache interface

SYNOPSIS

         use Cache::File;

         my $cache = Cache::File->new( cache_root => '/tmp/mycache',
                                       default_expires => '600 sec' );

       See Cache for the usage synopsis.

DESCRIPTION

       The Cache::File class implements the Cache interface.  This cache stores data in the filesystem so that
       it can be shared between processes and persists between process invocations.

CONSTRUCTOR

         my $cache = Cache::File->new( %options )

       The constructor takes cache properties as named arguments, for example:

         my $cache = Cache::File->new( cache_root => '/tmp/mycache',
                                       lock_level => Cache::File::LOCK_LOCAL(),
                                       default_expires => '600 sec' );

       Note that you MUST provide a cache_root property.

       See 'PROPERTIES' below and in the Cache documentation for a list of all available properties that can be
       set.

METHODS

       See 'Cache' for the API documentation.

PROPERTIES

       Cache::File adds the following properties in addition to those discussed in the 'Cache' documentation.

       cache_root
           Used  to  specify  the location of the cache store directory.  All methods will work ONLY data stored
           within this directory.  This parameter is REQUIRED when creating a Cache::File instance.

            my $ns = $c->cache_root();

       cache_depth
           The number of subdirectories deep to store cache entires.  This should be large enough that no  cache
           directory has more than a few hundred object.  Defaults to 2 unless explicitly set.

            my $depth = $c->cache_depth();

       cache_umask
           Specifies  the  umask  to  use when creating entries in the cache directory.  By default the umask is
           '077', indicating that only the same user may access the cache files.

            my $umask = $c->cache_umask();

       lock_level
           Specify the level of locking to be used.  There are three different levels available:

       Cache::File::LOCK_NONE()
           No locking is performed.  Useful when you can guarantee only one process will be accessing the  cache
           at a time.

       Cache::File::LOCK_LOCAL()
           Locking  is  performed,  but  it  is  not  suitable for use over NFS filesystems.  However it is more
           efficient.

       Cache::File::LOCK_NFS()
           Locking is performed in a way that is suitable for use on NFS filesystems.

        my $level = $c->cache_lock_level();

CAVEATS

       There are a couple of caveats in the current implementation of Cache::File.  None of these will present a
       problem in using the class, it's more of a TODO list of things that could be done better.

       external cache modification (and re-syncronization)
           Cache::File maintains indexes of entries in the cache, including the number of entries and the  total
           size.   Currently  there  is no process of checking that the count or size are in syncronization with
           the actual data on disk, and thus any modifications to the cache store by another program (eg. a user
           shell) will result in an inconsitency in the index.  A better process would  be  for  Cache::File  to
           resyncronize  at  an  appropriate  time  (eg whenever the size or count is initially requested - this
           would only need happen once per instance).  This resyncronization would involve calculating the total
           size and count as well as checking that entries in the index accurately reflect what is on  the  disk
           (and removing any entries that have dissapeared or adding any new ones).

       index efficiency
           Currently  Berkeley  DB's  are used for indexes of expiry time, last use and entry age.  They use the
           BTREE variant in order to implement a heap (see Cache::File::Heap).  This is probably  not  the  most
           efficient  format  and  having 3 separate index files adds overhead.  These are also cross-referenced
           with a fourth index file that uses a normal hash db  and  contains  all  these  time  stamps  (frozen
           together  with the validity object to a single scalar via Storable) indexed by key.  Needless to say,
           all this could be done more efficiently - probably by using a single index in a custom format.

       locking efficiency
           Currently LOCK_LOCAL is not implemented (if uses the same code as LOCK_NFS).

           There are two points of locking in Cache::File, index locking and entry locking.  The  index  locking
           is  always  exclusive  and the lock is required briefly during most operations.  The entry locking is
           either shared or exclusive and is also required during most operations.   When  locking  is  enabled,
           File::NFSLock  is  used  to  provide  the locking for both situations.  This is not overly efficient,
           especially as the entry lock is only ever grabbed whilst the index lock is held.

SEE ALSO

       Cache

AUTHOR

        Chris Leishman <chris@leishman.org>
        Based on work by DeWitt Clinton <dewitt@unto.net>

COPYRIGHT

        Copyright (C) 2003-2006 Chris Leishman.  All Rights Reserved.

       This module is distributed on an "AS IS" basis,  WITHOUT  WARRANTY  OF  ANY  KIND,  either  expressed  or
       implied.  This  program  is free software; you can redistribute or modify it under the same terms as Perl
       itself.

       $Id: File.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $

perl v5.34.0                                       2022-06-09                                   Cache::File(3pm)