Cache::File(3pm) - phpMan

Cache::File(3pm) User Contributed Perl Documentation Cache::File(3pm)

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.