1Cache::File(3) User Contributed Perl Documentation Cache::File(3)
2
6 Cache::File - Filesystem based implementation of the Cache interface
7
9 use Cache::File;
10 my $cache = Cache::File->new( cache_root => '/tmp/mycache',
12 default_expires => '600 sec' );
13 See Cache for the usage synopsis.
15
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
22 my $cache = Cache::File->new( %options )
23 The constructor takes cache properties as named arguments, for example:
25 my $cache = Cache::File->new( cache_root => '/tmp/mycache',
27 lock_level => Cache::File::LOCK_LOCAL(),
28 default_expires => '600 sec' );
29 Note that you MUST provide a cache_root property.
31 See 'PROPERTIES' below and in the Cache documentation for a list of all
33 available properties that can be set.
34
36 See 'Cache' for the API documentation.
37
39 Cache::File adds the following properties in addition to those
40 discussed in the 'Cache' documentation.
41 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 my $ns = $c->cache_root();
48 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 my $depth = $c->cache_depth();
55 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 my $umask = $c->cache_umask();
62 lock_level
64 Specify the level of locking to be used. There are three different
65 levels available:
66 Cache::File::LOCK_NONE()
68 No locking is performed. Useful when you can guarantee only
69 one process will be accessing the cache at a time.
70 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 Cache::File::LOCK_NFS()
76 Locking is performed in a way that is suitable for use on NFS
77 filesystems.
78 my $level = $c->cache_lock_level();
80
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 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 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 locking efficiency
113 Currently LOCK_LOCAL is not implemented (if uses the same code as
114 LOCK_NFS).
115 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
126 Cache
127
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 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 $Id: File.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $
140
142 Hey! The above document had some coding errors, which are explained
143 below:
144 Around line 588:
146 You forgot a '=back' before '=head1'
147perl v5.12.0 2006-01-31 Cache::File(3)