1Mmap(3)               User Contributed Perl Documentation              Mmap(3)
2
3
4

NAME

6       Cache::Mmap - Shared data cache using memory mapped files
7

SYNOPSIS

9         use Cache::Mmap;
10
11         $cache=Cache::Mmap->new($filename,\%options);
12
13         $val1=$cache->read($key1);
14         $cache->write($key2,$val2);
15         $cache->delete($key3);
16

DESCRIPTION

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
24       Cache entries are assigned to "buckets" within the cache file,
25       depending on the key. Within each bucket, entries are stored
26       approximately in order of last access, so that frequently accessed
27       entries will move to the head of the bucket, thus decreasing access
28       time. Concurrent accesses to the same bucket are prevented by file
29       locking of the relevant section of the cache file.
30

CLASS METHODS

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
39           permissions (0600)
40               Sets the file permissions for the cache file if it doesn't
41               already exist.
42
43           buckets (13)
44               Sets the number of buckets inside the cache file. A larger
45               number 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
49           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
56           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
61               performance.
62
63           strings (0)
64               If true, cache entries are treated as strings, rather than
65               references. This will help performance for string-only caches,
66               as no time will be taken to serialize cache entries.
67
68           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
74           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
79           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
86               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
90               If this routine is not provided, only values already in the
91               cache will ever be returned.
92
93               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
97               "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
105                     return (Cache::Mmap::CMM_keep_expired, undef);
106
107               "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
112           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
117           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
125           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
130               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
136           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
145           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

METHODS

152   CACHE DATA METHODS
153       These are the everyday methods used to access the data stored by the
154       cache.
155
156       read($key)
157           Reads an entry from the cache, or from the underlying data if not
158           cached.  Returns the value in scalar context, and "($found,$value)"
159           in list context, where $found is true if the item was found in
160           either the cache or the underlying data.
161
162       write($key,$val)
163           Writes an entry into the cache, and depending on the configuration,
164           into the underlying data.
165
166       delete($key)
167           Deletes an entry from the cache, and depending on "new()" options,
168           from the underlying data.  Returns the value in scalar context, and
169           "($found,$value)" in list context, where $found is true if the item
170           was found in the cache.
171
172       entries()
173       entries(0)
174           Returns a list of the keys of entries held in the cache. Note that
175           this list may be immediately out of date, due to the shared nature
176           of the cache. Entries may be added or removed by other processes
177           between this list being generated and when it is used.
178
179       entries(1)
180           Returns a list of hashrefs representing entries held in the cache.
181           The following keys are present in each hashref:
182
183             key    The key used to identify the entry
184             time   The time the entry was stored (seconds since the epoch)
185             dirty  Whether the entry needs writing to the underlying data
186
187           The same caveat applies to the currency of this information as
188           above.
189
190       entries(2)
191           As entries(1), with the addition of a "value" element in each
192           hashref, holding the value stored in the cache entry.
193
194       quick_clear()
195           Forcefully delete the cache, with prejudice. Unwritten dirty
196           elements are not written back to the underlying data source; they
197           are simply thrown away.
198
199   CONFIGURATION METHODS
200       These methods are used to examine/update the configuration of a cache.
201       Most of these methods are read-only, and the value returned may be
202       different to that passed to the constructor, since the cache may have
203       been created by an earlier process which specified different
204       parameters.
205
206       buckets()
207           Returns the number of buckets in the cache file.
208
209       bucketsize()
210           Returns the size of buckets (in bytes) in the cache file.
211
212       cachenegative()
213           Returns true if items not found in the underlying data are cached
214           anyway.
215
216       context()
217           Returns the context data for reads and writes to the underlying
218           data.
219
220       context($context)
221           Provides new context data for reads and writes to the underlying
222           data.
223
224       expiry()
225           Returns the time in seconds cache entries are considered valid for,
226           or zero for indefinite validity.
227
228       pagesize()
229           Returns the page size (in bytes) of the cache file.
230
231       strings()
232           Returns true if the cache stores strings rather than references.
233
234       writethrough()
235           Returns true if items written to the cache are immediately written
236           to the underlying data.
237

AUTHOR

239       Copyright (C) Institute of Physics Publishing 2002-2008
240
241               Peter Haworth <pmh@edison.ioppublishing.com>
242
243       You may distribute under the terms of the GPL or the Artistic License,
244       as distributed with Perl.
245
246
247
248perl v5.32.1                      2021-01-26                           Mmap(3)
Impressum