phpman > perldoc > 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.

SEE ALSO
    Cache

AUTHOR
     Chris Leishman <chris AT leishman.org>
     Based on work by DeWitt Clinton <dewitt AT 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 $