1Cache::File(3)        User Contributed Perl Documentation       Cache::File(3)
2
3
4

NAME

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

SYNOPSIS

9         use Cache::File;
10
11         my $cache = Cache::File->new( cache_root => '/tmp/mycache',
12                                       default_expires => '600 sec' );
13
14       See Cache for the usage synopsis.
15

DESCRIPTION

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

CONSTRUCTOR

22         my $cache = Cache::File->new( %options )
23
24       The constructor takes cache properties as named arguments, for example:
25
26         my $cache = Cache::File->new( cache_root => '/tmp/mycache',
27                                       lock_level => Cache::File::LOCK_LOCAL(),
28                                       default_expires => '600 sec' );
29
30       Note that you MUST provide a cache_root property.
31
32       See 'PROPERTIES' below and in the Cache documentation for a list of all
33       available properties that can be set.
34

METHODS

36       See 'Cache' for the API documentation.
37

PROPERTIES

39       Cache::File adds the following properties in addition to those
40       discussed in the 'Cache' documentation.
41
42       cache_root
43           Used to specify the location of the cache store directory.  All
44           methods will work ONLY data stored within this directory.  This
45           parameter is REQUIRED when creating a Cache::File instance.
46
47            my $ns = $c->cache_root();
48
49       cache_depth
50           The number of subdirectories deep to store cache entires.  This
51           should be large enough that no cache directory has more than a few
52           hundred object.  Defaults to 2 unless explicitly set.
53
54            my $depth = $c->cache_depth();
55
56       cache_umask
57           Specifies the umask to use when creating entries in the cache
58           directory.  By default the umask is '077', indicating that only the
59           same user may access the cache files.
60
61            my $umask = $c->cache_umask();
62
63       lock_level
64           Specify the level of locking to be used.  There are three different
65           levels available:
66
67       Cache::File::LOCK_NONE()
68           No locking is performed.  Useful when you can guarantee only one
69           process will be accessing the cache at a time.
70
71       Cache::File::LOCK_LOCAL()
72           Locking is performed, but it is not suitable for use over NFS
73           filesystems.  However it is more efficient.
74
75       Cache::File::LOCK_NFS()
76           Locking is performed in a way that is suitable for use on NFS
77           filesystems.
78
79        my $level = $c->cache_lock_level();
80

CAVEATS

82       There are a couple of caveats in the current implementation of
83       Cache::File.  None of these will present a problem in using the class,
84       it's more of a TODO list of things that could be done better.
85
86       external cache modification (and re-syncronization)
87           Cache::File maintains indexes of entries in the cache, including
88           the number of entries and the total size.  Currently there is no
89           process of checking that the count or size are in syncronization
90           with the actual data on disk, and thus any modifications to the
91           cache store by another program (eg. a user shell) will result in an
92           inconsitency in the index.  A better process would be for
93           Cache::File to resyncronize at an appropriate time (eg whenever the
94           size or count is initially requested - this would only need happen
95           once per instance).  This resyncronization would involve
96           calculating the total size and count as well as checking that
97           entries in the index accurately reflect what is on the disk (and
98           removing any entries that have dissapeared or adding any new ones).
99
100       index efficiency
101           Currently Berkeley DB's are used for indexes of expiry time, last
102           use and entry age.  They use the BTREE variant in order to
103           implement a heap (see Cache::File::Heap).  This is probably not the
104           most efficient format and having 3 separate index files adds
105           overhead.  These are also cross-referenced with a fourth index file
106           that uses a normal hash db and contains all these time stamps
107           (frozen together with the validity object to a single scalar via
108           Storable) indexed by key.  Needless to say, all this could be done
109           more efficiently - probably by using a single index in a custom
110           format.
111
112       locking efficiency
113           Currently LOCK_LOCAL is not implemented (if uses the same code as
114           LOCK_NFS).
115
116           There are two points of locking in Cache::File, index locking and
117           entry locking.  The index locking is always exclusive and the lock
118           is required briefly during most operations.  The entry locking is
119           either shared or exclusive and is also required during most
120           operations.  When locking is enabled, File::NFSLock is used to
121           provide the locking for both situations.  This is not overly
122           efficient, especially as the entry lock is only ever grabbed whilst
123           the index lock is held.
124

SEE ALSO

126       Cache
127

AUTHOR

129        Chris Leishman <chris@leishman.org>
130        Based on work by DeWitt Clinton <dewitt@unto.net>
131
133        Copyright (C) 2003-2006 Chris Leishman.  All Rights Reserved.
134
135       This module is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
136       KIND, either expressed or implied. This program is free software; you
137       can redistribute or modify it under the same terms as Perl itself.
138
139       $Id: File.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $
140
141
142
143perl v5.34.0                      2022-01-20                    Cache::File(3)
Impressum