1Mmap(3) User Contributed Perl Documentation Mmap(3)
2
6 Cache::Mmap - Shared data cache using memory mapped files
7
9 use Cache::Mmap;
10 $cache=Cache::Mmap->new($filename,\%options);
12 $val1=$cache->read($key1);
14 $cache->write($key2,$val2);
15 $cache->delete($key3);
16
18 This module implements a shared data cache, using memory mapped files.
19 If routines are provided which interact with the underlying data,
20 access to the cache is completely transparent, and the module handles
21 all the details of refreshing cache contents, and updating underlying
22 data, if necessary.
23 Cache entries are assigned to "buckets" within the cache file, depend‐
25 ing on the key. Within each bucket, entries are stored approximately in
26 order of last access, so that frequently accessed entries will move to
27 the head of the bucket, thus decreasing access time. Concurrent
28 accesses to the same bucket are prevented by file locking of the rele‐
29 vant section of the cache file.
30
32 new($filename,\%options)
33 Creates a new cache object. If the file named by $filename does not
34 already exist, it will be created. If the cache object cannot be
35 created for any reason, an exception will be thrown. Various
36 options may be set in %options, which affect the behaviour of the
37 cache (defaults in parentheses):
38 permissions (0600)
40 Sets the file permissions for the cache file if it doesn't
41 already exist.
42 buckets (13)
44 Sets the number of buckets inside the cache file. A larger num‐
45 ber of buckets will give better performance for a cache with
46 many accesses, as there will be less chance of concurrent
47 access to the same bucket.
48 bucketsize (1024)
50 Sets the size of each bucket, in bytes. A larger bucket size
51 will be needed to store large cache entries. If the bucketsize
52 is not large enough to hold a particular entry, it will still
53 be passed between the underlying data and the application in
54 its entirety, but will not be stored in the cache.
55 pagesize (1024)
57 Sets the alignment of buckets within the file. The file header
58 will be extended to this size, and bucket sizes will be rounded
59 up to the nearest multiple. Choosing a pagesize equal to the
60 virtual memory page size of the host system should improve per‐
61 formance.
62 strings (0)
64 If true, cache entries are treated as strings, rather than ref‐
65 erences. This will help performance for string-only caches, as
66 no time will be taken to serialize cache entries.
67 expiry (0)
69 If non-zero, sets the length of time, in seconds, which cache
70 entries are considered valid. A new entry will be fetched from
71 the underlying data if an expired cache entry would otherwise
72 have been returned.
73 context (undef)
75 This value is passed to the read/write/delete routines below,
76 to provide context. This will typically be a database handle,
77 used to fetch data from.
78 read (undef)
80 Provides a code reference to a routine which will fetch entries
81 from the underlying data. Called as "$read->($key,$context)",
82 this routine should return a list "($found,$value)", where
83 $found is true if the entry could be found in the underlying
84 data, and $value is the value to cache.
85 If the routine only returns a single scalar, that will be taken
87 as the value, and $found will be set to true if the value is
88 defined.
89 If this routine is not provided, only values already in the
91 cache will ever be returned.
92 There are currently two special values of $found which cause
94 slightly different behaviour. These are constants which may be
95 imported in the "use" statement.
96 "Cache::Mmap::CMM_keep_expired"
98 Use the previously cached value, even if it has expired.
99 This is useful if the underlying data source has become
100 unavailable for some reason. Note that even though the
101 value returned will be ignored in this case, it must be
102 returned to avoid $found being interpreted as a single
103 scalar:
104 return (Cache::Mmap::CMM_keep_expired, undef);
106 "Cache::Mmap::CMM_keep_expired_refresh"
108 This causes the same behaviour as "CMM_keep_expired", but
109 the cache entry's expiry time will be reset as if a value
110 had been successfully read from the underlying data.
111 cachenegative (0)
113 If true, even unsuccessful fetches from the underlying data are
114 cached. This can be useful to only search the underlying data
115 once for each required key.
116 write (undef)
118 Provides a code reference to a routine which will write cache
119 entries into the underlying data. This routine will be called
120 by write(), to synchronise the underlying data with the cache.
121 Called as "$write->($key,$val,$context)". If the routine is
122 not provided, the underlying data will not be synchronised
123 after cache writes.
124 writethrough (1)
126 If true, the "write" routine above will be called as soon as
127 write() is called. This provides immediate synchronisation of
128 underlying data and cache contents.
129 If false, the "write" routine will be called for each cache
131 entry which no longer fits in its bucket after a cache read or
132 write. This provides a write-as-necessary behaviour, which may
133 be more efficient than the writethrough behaviour. However,
134 only data fetched through the cache will reflect these changes.
135 delete (undef)
137 Provides a code reference to a routine which will delete items
138 from the underlying data. This routine will be called by
139 delete(), to synchronise the underlying data with the cache.
140 Called as "$delete->($key,$cval,$context)", where $cval is the
141 value currently stored in the cache. If this routine is not
142 provided, entries deleted from the cache have no effect on the
143 underlying data.
144 An alternative to supplying a "write" routine, is to call delete()
146 after updating the underlying data. Note however, that in the case
147 of databases, this should be done after committing the update, so
148 that a concurrent process doesn't reload the cache between being
149 the entry being deleted, and the database updates being committed.
150
152 CACHE DATA METHODS
153 These are the everyday methods used to access the data stored by the
155 cache.
156 read($key)
158 Reads an entry from the cache, or from the underlying data if not
159 cached. Returns the value in scalar context, and "($found,$value)"
160 in list context, where $found is true if the item was found in
161 either the cache or the underlying data.
162 write($key,$val)
164 Writes an entry into the cache, and depending on the configuration,
165 into the underlying data.
166 delete($key)
168 Deletes an entry from the cache, and depending on "new()" options,
169 from the underlying data. Returns the value in scalar context, and
170 "($found,$value)" in list context, where $found is true if the item
171 was found in the cache.
172 entries()
174 entries(0)
175 Returns a list of the keys of entries held in the cache. Note that
176 this list may be immediately out of date, due to the shared nature
177 of the cache. Entries may be added or removed by other processes
178 between this list being generated and when it is used.
179 entries(1)
181 Returns a list of hashrefs representing entries held in the cache.
182 The following keys are present in each hashref:
183 key The key used to identify the entry
185 time The time the entry was stored (seconds since the epoch)
186 dirty Whether the entry needs writing to the underlying data
187 The same caveat applies to the currency of this information as
189 above.
190 entries(2)
192 As entries(1), with the addition of a "value" element in each
193 hashref, holding the value stored in the cache entry.
194 quick_clear()
196 Forcefully delete the cache, with prejudice. Unwritten dirty ele‐
197 ments are not written back to the underlying data source; they are
198 simply thrown away.
199 CONFIGURATION METHODS
201 These methods are used to examine/update the configuration of a cache.
203 Most of these methods are read-only, and the value returned may be dif‐
204 ferent to that passed to the constructor, since the cache may have been
205 created by an earlier process which specified different parameters.
206 buckets()
208 Returns the number of buckets in the cache file.
209 bucketsize()
211 Returns the size of buckets (in bytes) in the cache file.
212 cachenegative()
214 Returns true if items not found in the underlying data are cached
215 anyway.
216 context()
218 Returns the context data for reads and writes to the underlying
219 data.
220 context($context)
222 Provides new context data for reads and writes to the underlying
223 data.
224 expiry()
226 Returns the time in seconds cache entries are considered valid for,
227 or zero for indefinite validity.
228 pagesize()
230 Returns the page size (in bytes) of the cache file.
231 strings()
233 Returns true if the cache stores strings rather than references.
234 writethrough()
236 Returns true if items written to the cache are immediately written
237 to the underlying data.
238
240 Copyright (C) Institute of Physics Publishing 2002-2005
241 Peter Haworth <pmh@edison.ioppublishing.com>
243 You may distribute under the terms of the GPL or the Artistic License,
245 as distributed with Perl.
246perl v5.8.8 2005-11-15 Mmap(3)