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

NAME

6       Cache::FastMmap - Uses an mmap'ed file to act as a shared memory
7       interprocess cache
8

SYNOPSIS

10         use Cache::FastMmap;
11
12         # Uses vaguely sane defaults
13         $Cache = Cache::FastMmap->new();
14
15         # Uses Storable to serialize $Value to bytes for storage
16         $Cache->set($Key, $Value);
17         $Value = $Cache->get($Key);
18
19         $Cache = Cache::FastMmap->new(serializer => '');
20
21         # Stores stringified bytes of $Value directly
22         $Cache->set($Key, $Value);
23         $Value = $Cache->get($Key);
24

ABSTRACT

26       A shared memory cache through an mmap'ed file. It's core is written in
27       C for performance. It uses fcntl locking to ensure multiple processes
28       can safely access the cache at the same time. It uses a basic LRU
29       algorithm to keep the most used entries in the cache.
30

DESCRIPTION

32       In multi-process environments (eg mod_perl, forking daemons, etc), it's
33       common to want to cache information, but have that cache shared between
34       processes. Many solutions already exist, and may suit your situation
35       better:
36
37       •   MLDBM::Sync - acts as a database, data is not automatically
38           expired, slow
39
40       •   IPC::MM - hash implementation is broken, data is not automatically
41           expired, slow
42
43       •   Cache::FileCache - lots of features, slow
44
45       •   Cache::SharedMemoryCache - lots of features, VERY slow. Uses
46           IPC::ShareLite which freeze/thaws ALL data at each read/write
47
48       •   DBI - use your favourite RDBMS. can perform well, need a DB server
49           running. very global. socket connection latency
50
51       •   Cache::Mmap - similar to this module, in pure perl. slows down with
52           larger pages
53
54       •   BerkeleyDB - very fast (data ends up mostly in shared memory cache)
55           but acts as a database overall, so data is not automatically
56           expired
57
58       In the case I was working on, I needed:
59
60       •   Automatic expiry and space management
61
62       •   Very fast access to lots of small items
63
64       •   The ability to fetch/store many items in one go
65
66       Which is why I developed this module. It tries to be quite efficient
67       through a number of means:
68
69       •   Core code is written in C for performance
70
71       •   It uses multiple pages within a file, and uses Fcntl to only lock a
72           page at a time to reduce contention when multiple processes access
73           the cache.
74
75       •   It uses a dual level hashing system (hash to find page, then hash
76           within each page to find a slot) to make most "get()" calls O(1)
77           and fast
78
79       •   On each "set()", if there are slots and page space available, only
80           the slot has to be updated and the data written at the end of the
81           used data space. If either runs out, a re-organisation of the page
82           is performed to create new slots/space which is done in an
83           efficient way
84
85       The class also supports read-through, and write-back or write-through
86       callbacks to access the real data if it's not in the cache, meaning
87       that code like this:
88
89         my $Value = $Cache->get($Key);
90         if (!defined $Value) {
91           $Value = $RealDataSource->get($Key);
92           $Cache->set($Key, $Value)
93         }
94
95       Isn't required, you instead specify in the constructor:
96
97         Cache::FastMmap->new(
98           ...
99           context => $RealDataSourceHandle,
100           read_cb => sub { $_[0]->get($_[1]) },
101           write_cb => sub { $_[0]->set($_[1], $_[2]) },
102         );
103
104       And then:
105
106         my $Value = $Cache->get($Key);
107
108         $Cache->set($Key, $NewValue);
109
110       Will just work and will be read/written to the underlying data source
111       as needed automatically.
112

PERFORMANCE

114       If you're storing relatively large and complex structures into the
115       cache, then you're limited by the speed of the Storable module.  If
116       you're storing simple structures, or raw data, then Cache::FastMmap has
117       noticeable performance improvements.
118
119       See <http://cpan.robm.fastmail.fm/cache_perf.html> for some comparisons
120       to other modules.
121

COMPATIBILITY

123       Cache::FastMmap uses mmap to map a file as the shared cache space, and
124       fcntl to do page locking. This means it should work on most UNIX like
125       operating systems.
126
127       Ash Berlin has written a Win32 layer using MapViewOfFile et al. to
128       provide support for Win32 platform.
129

MEMORY SIZE

131       Because Cache::FastMmap mmap's a shared file into your processes memory
132       space, this can make each process look quite large, even though it's
133       just mmap'd memory that's shared between all processes that use the
134       cache, and may even be swapped out if the cache is getting low usage.
135
136       However, the OS will think your process is quite large, which might
137       mean you hit some BSD::Resource or 'ulimits' you set previously that
138       you thought were sane, but aren't anymore, so be aware.
139

CACHE FILES AND OS ISSUES

141       Because Cache::FastMmap uses an mmap'ed file, when you put values into
142       the cache, you are actually "dirtying" pages in memory that belong to
143       the cache file. Your OS will want to write those dirty pages back to
144       the file on the actual physical disk, but the rate it does that at is
145       very OS dependent.
146
147       In Linux, you have some control over how the OS writes those pages back
148       using a number of parameters in /proc/sys/vm
149
150         dirty_background_ratio
151         dirty_expire_centisecs
152         dirty_ratio
153         dirty_writeback_centisecs
154
155       How you tune these depends heavily on your setup.
156
157       As an interesting point, if you use a highmem linux kernel, a change
158       between 2.6.16 and 2.6.20 made the kernel flush memory a LOT more.
159       There's details in this kernel mailing list thread:
160       <http://www.uwsg.iu.edu/hypermail/linux/kernel/0711.3/0804.html>
161
162       In most cases, people are not actually concerned about the persistence
163       of data in the cache, and so are happy to disable writing of any cache
164       data back to disk at all. Baically what they want is an in memory only
165       shared cache. The best way to do that is to use a "tmpfs" filesystem
166       and put all cache files on there.
167
168       For instance, all our machines have a /tmpfs mount point that we create
169       in /etc/fstab as:
170
171         none /tmpfs tmpfs defaults,noatime,size=1000M 0 0
172
173       And we put all our cache files on there. The tmpfs filesystem is smart
174       enough to only use memory as required by files actually on the tmpfs,
175       so making it 1G in size doesn't actually use 1G of memory, it only uses
176       as much as the cache files we put on it. In all cases, we ensure that
177       we never run out of real memory, so the cache files effectively act
178       just as named access points to shared memory.
179
180       Some people have suggested using anonymous mmaped memory. Unfortunately
181       we need a file descriptor to do the fcntl locking on, so we'd have to
182       create a separate file on a filesystem somewhere anyway. It seems
183       easier to just create an explicit "tmpfs" filesystem.
184

PAGE SIZE AND KEY/VALUE LIMITS

186       To reduce lock contention, Cache::FastMmap breaks up the file into
187       pages. When you get/set a value, it hashes the key to get a page, then
188       locks that page, and uses a hash table within the page to get/store the
189       actual key/value pair.
190
191       One consequence of this is that you cannot store values larger than a
192       page in the cache at all. Attempting to store values larger than a page
193       size will fail (the set() function will return false).
194
195       Also keep in mind that each page has it's own hash table, and that we
196       store the key and value data of each item. So if you are expecting to
197       store large values and/or keys in the cache, you should use page sizes
198       that are definitely larger than your largest key + value size + a few
199       kbytes for the overhead.
200

USAGE

202       Because the cache uses shared memory through an mmap'd file, you have
203       to make sure each process connects up to the file. There's probably two
204       main ways to do this:
205
206       •   Create the cache in the parent process, and then when it forks,
207           each child will inherit the same file descriptor, mmap'ed memory,
208           etc and just work. This is the recommended way. (BEWARE: This only
209           works under UNIX as Win32 has no concept of forking)
210
211       •   Explicitly connect up in each forked child to the share file. In
212           this case, make sure the file already exists and the children
213           connect with init_file => 0 to avoid deleting the cache contents
214           and possible race corruption conditions. Also be careful that
215           multiple children may race to create the file at the same time,
216           each overwriting and corrupting content. Use a separate lock file
217           if you must to ensure only one child creates the file. (This is the
218           only possible way under Win32)
219
220       The first way is usually the easiest. If you're using the cache in a
221       Net::Server based module, you'll want to open the cache in the
222       "pre_loop_hook", because that's executed before the fork, but after the
223       process ownership has changed and any chroot has been done.
224
225       In mod_perl, just open the cache at the global level in the appropriate
226       module, which is executed as the server is starting and before it
227       starts forking children, but you'll probably want to chmod or chown the
228       file to the permissions of the apache process.
229

RELIABILITY

231       Cache::FastMmap is being used in an extensive number of systems at
232       www.fastmail.com and is regarded as extremely stable and reliable.
233       Development has in general slowed because there are currently no known
234       bugs and no additional needed features at this time.
235

METHODS

237       new(%Opts)
238           Create a new Cache::FastMmap object.
239
240           Basic global parameters are:
241
242share_file
243
244               File to mmap for sharing of data.  default on unix:
245               /tmp/sharefile-$pid-$time-$random default on windows:
246               %TEMP%\sharefile-$pid-$time-$random
247
248init_file
249
250               Clear any existing values and re-initialise file. Useful to do
251               in a parent that forks off children to ensure that file is
252               empty at the start (default: 0)
253
254               Note: This is quite important to do in the parent to ensure a
255               consistent file structure. The shared file is not perfectly
256               transaction safe, and so if a child is killed at the wrong
257               instant, it might leave the cache file in an inconsistent
258               state.
259
260serializer
261
262               Use a serialization library to serialize perl data structures
263               before storing in the cache. If not set, the raw value in the
264               variable passed to set() is stored as a string. You must set
265               this if you want to store anything other than basic scalar
266               values. Supported values are:
267
268                 ''         for none
269                 'storable' for 'Storable'
270                 'sereal'   for 'Sereal'
271                 'json'     for 'JSON'
272                 [ $s, $d ] for custom serializer/de-serializer
273
274               If this parameter has a value the module will attempt to load
275               the associated package and then use the API of that package to
276               serialize data before storing in the cache, and deserialize it
277               upon retrieval from the cache. (default: 'storable')
278
279               You can use a custom serializer/de-serializer by passing an
280               array-ref with two values. The first should be a subroutine
281               reference that takes the data to serialize as a single argument
282               and returns an octet stream to store. The second should be a
283               subroutine reference that takes the octet stream as a single
284               argument and returns the original data structure.
285
286               One thing to note, the data structure passed to the serializer
287               is always a *scalar* reference to the original data passed in
288               to the ->set(...)  call. If your serializer doesn't support
289               that, you might need to dereference it first before storing,
290               but rembember to return a reference again in the de-serializer.
291
292               (Note: Historically this module only supported a boolean value
293               for the `raw_values` parameter and defaulted to 0, which meant
294               it used Storable to serialze all values.)
295
296raw_values
297
298               Deprecated. Use serializer above
299
300compressor
301
302               Compress the value (but not the key) before storing into the
303               cache, using the compression package identified by the value of
304               the parameter. Supported values are:
305
306                 'zlib'     for 'Compress::Zlib'
307                 'lz4'      for 'Compress::LZ4'
308                 'snappy'   for 'Compress::Snappy'
309                 [ $c, $d ] for custom compressor/de-compressor
310
311               If this parameter has a value the module will attempt to load
312               the associated package and then use the API of that package to
313               compress data before storing in the cache, and uncompress it
314               upon retrieval from the cache. (default: undef)
315
316               You can use a custom compressor/de-compressor by passing an
317               array-ref with two values. The first should be a subroutine
318               reference that takes the data to compress as a single octet
319               stream argument and returns an octet stream to store. The
320               second should be a subroutine reference that takes the
321               compressed octet stream as a single argument and returns the
322               original uncompressed data.
323
324               (Note: Historically this module only supported a boolean value
325               for the `compress` parameter and defaulted to use
326               Compress::Zlib. The note for the old `compress` parameter
327               stated: "Some initial testing shows that the uncompressing
328               tends to be very fast, though the compressing can be quite
329               slow, so it's probably best to use this option only if you know
330               values in the cache are long-lived and have a high hit rate."
331
332               Comparable test results for the other compression tools are not
333               yet available; submission of benchmarks welcome. However, the
334               documentation for the 'Snappy' library
335               (http://google.github.io/snappy/) states: For instance,
336               compared to the fastest mode of zlib, Snappy is an order of
337               magnitude faster for most inputs, but the resulting compressed
338               files are anywhere from 20% to 100% bigger. )
339
340compress
341
342               Deprecated. Please use compressor, see above.
343
344enable_stats
345
346               Enable some basic statistics capturing. When enabled, every
347               read to the cache is counted, and every read to the cache that
348               finds a value in the cache is also counted. You can then
349               retrieve these values via the get_statistics() call. This
350               causes every read action to do a write on a page, which can
351               cause some more IO, so it's disabled by default. (default: 0)
352
353expire_time
354
355               Maximum time to hold values in the cache in seconds. A value of
356               0 means does no explicit expiry time, and values are expired
357               only based on LRU usage. Can be expressed as 1m, 1h, 1d for
358               minutes/hours/days respectively. (default: 0)
359
360           You may specify the cache size as:
361
362cache_size
363
364               Size of cache. Can be expresses as 1k, 1m for kilobytes or
365               megabytes respectively. Automatically guesses page size/page
366               count values.
367
368           Or specify explicit page size/page count values. If none of these
369           are specified, the values page_size = 64k and num_pages = 89 are
370           used.
371
372page_size
373
374               Size of each page. Must be a power of 2 between 4k and 1024k.
375               If not, is rounded to the nearest value.
376
377num_pages
378
379               Number of pages. Should be a prime number for best hashing
380
381           The cache allows the use of callbacks for reading/writing data to
382           an underlying data store.
383
384context
385
386               Opaque reference passed as the first parameter to any callback
387               function if specified
388
389read_cb
390
391               Callback to read data from the underlying data store.  Called
392               as:
393
394                 $read_cb->($context, $Key)
395
396               Should return the value to use. This value will be saved in the
397               cache for future retrievals. Return undef if there is no value
398               for the given key
399
400write_cb
401
402               Callback to write data to the underlying data store.  Called
403               as:
404
405                 $write_cb->($context, $Key, $Value, $ExpiryTime)
406
407               In 'write_through' mode, it's always called as soon as a
408               set(...)  is called on the Cache::FastMmap class. In
409               'write_back' mode, it's called when a value is expunged from
410               the cache if it's been changed by a set(...) rather than read
411               from the underlying store with the read_cb above.
412
413               Note: Expired items do result in the write_cb being called if
414               'write_back' caching is enabled and the item has been changed.
415               You can check the $ExpiryTime against "time()" if you only want
416               to write back values which aren't expired.
417
418               Also remember that write_cb may be called in a different
419               process to the one that placed the data in the cache in the
420               first place
421
422delete_cb
423
424               Callback to delete data from the underlying data store.  Called
425               as:
426
427                 $delete_cb->($context, $Key)
428
429               Called as soon as remove(...) is called on the Cache::FastMmap
430               class
431
432cache_not_found
433
434               If set to true, then if the read_cb is called and it returns
435               undef to say nothing was found, then that information is stored
436               in the cache, so that next time a get(...) is called on that
437               key, undef is returned immediately rather than again calling
438               the read_cb
439
440write_action
441
442               Either 'write_back' or 'write_through'. (default:
443               write_through)
444
445allow_recursive
446
447               If you're using a callback function, then normally the cache is
448               not re-enterable, and attempting to call a get/set on the cache
449               will cause an error. By setting this to one, the cache will
450               unlock any pages before calling the callback. During the unlock
451               time, other processes may change data in current cache page,
452               causing possible unexpected effects. You shouldn't set this
453               unless you know you want to be able to recall to the cache
454               within a callback.  (default: 0)
455
456empty_on_exit
457
458               When you have 'write_back' mode enabled, then you really want
459               to make sure all values from the cache are expunged when your
460               program exits so any changes are written back.
461
462               The trick is that we only want to do this in the parent
463               process, we don't want any child processes to empty the cache
464               when they exit.  So if you set this, it takes the PID via $$,
465               and only calls empty in the DESTROY method if $$ matches the
466               pid we captured at the start. (default: 0)
467
468unlink_on_exit
469
470               Unlink the share file when the cache is destroyed.
471
472               As with empty_on_exit, this will only unlink the file if the
473               DESTROY occurs in the same PID that the cache was created in so
474               that any forked children don't unlink the file.
475
476               This value defaults to 1 if the share_file specified does not
477               already exist. If the share_file specified does already exist,
478               it defaults to 0.
479
480catch_deadlocks
481
482               Sets an alarm(10) before each page is locked via
483               fcntl(F_SETLKW) to catch any deadlock. This used to be the
484               default behaviour, but it's not really needed in the default
485               case and could clobber sub-second Time::HiRes alarms setup by
486               other code. Defaults to 0.
487
488       get($Key, [ \%Options ])
489           Search cache for given Key. Returns undef if not found. If read_cb
490           specified and not found, calls the callback to try and find the
491           value for the key, and if found (or 'cache_not_found' is set),
492           stores it into the cache and returns the found value.
493
494           %Options is optional, and is used by get_and_set() to control the
495           locking behaviour. For now, you should probably ignore it unless
496           you read the code to understand how it works
497
498       set($Key, $Value, [ \%Options ])
499           Store specified key/value pair into cache
500
501           %Options is optional. If it's not a hash reference, it's assumed to
502           be an explicit expiry time for the key being set, this is to make
503           set() compatible with the Cache::Cache interface
504
505           If a hash is passed, the only useful entries right now are
506           expire_on to set an explicit expiry time for this entry (epoch
507           seconds), or expire_time to set an explicit relative future expiry
508           time for this entry in seconds/minutes/days in the same format as
509           passed to the new constructor.
510
511           Some other options are used internally, such as by get_and_set() to
512           control the locking behaviour. For now, you should probably ignore
513           it unless you read the code to understand how it works
514
515           This method returns true if the value was stored in the cache,
516           false otherwise. See the PAGE SIZE AND KEY/VALUE LIMITS section for
517           more details.
518
519       get_and_set($Key, $AtomicSub)
520           Atomically retrieve and set the value of a Key.
521
522           The page is locked while retrieving the $Key and is unlocked only
523           after the value is set, thus guaranteeing the value does not change
524           between the get and set operations.
525
526           $AtomicSub is a reference to a subroutine that is called to
527           calculate the new value to store. $AtomicSub gets $Key, the current
528           value from the cache, and an options hash as paramaters. Currently
529           the only option passed is the expire_on of the item.
530
531           It should return the new value to set in the cache for the given
532           $Key, and an optional hash of arguments in the same format as would
533           be passed to a "set()" call.
534
535           If $AtomicSub returns an empty list, no value is stored back in the
536           cache. This avoids updating the expiry time on an entry if you want
537           to do a "get if in cache, store if not present" type callback.
538
539           For example:
540
541           •   To atomically increment a value in the cache
542
543                 $Cache->get_and_set($Key, sub { return $_[1]+1; });
544
545           •   To add an item to a cached list and set the expiry time
546               depending on the size of the list
547
548                 $Cache->get_and_set($Key, sub ($, $v) {
549                   push @$v, $item;
550                   return ($v, { expire_time => @$v > 2 ? '10s' : '2m' });
551                 });
552
553           •   To update a counter, but maintain the original expiry time
554
555                 $Cache->get_and_set($Key, sub {
556                   return ($_[1]+1, { expire_on => $_[2]->{expire_on} );
557                 });
558
559           In scalar context the return value from "get_and_set()", is the
560           *new* value stored back into the cache.
561
562           In list context, a two item array is returned; the new value stored
563           back into the cache and a boolean that's true if the value was
564           stored in the cache, false otherwise. See the PAGE SIZE AND
565           KEY/VALUE LIMITS section for more details.
566
567           Notes:
568
569           •   Do not perform any get/set operations from the callback sub, as
570               these operations lock the page and you may end up with a dead
571               lock!
572
573           •   If your sub does a die/throws an exception, the page will
574               correctly be unlocked (1.15 onwards)
575
576       remove($Key, [ \%Options ])
577           Delete the given key from the cache
578
579           %Options is optional, and is used by get_and_remove() to control
580           the locking behaviour. For now, you should probably ignore it
581           unless you read the code to understand how it works
582
583       get_and_remove($Key)
584           Atomically retrieve value of a Key while removing it from the
585           cache.
586
587           The page is locked while retrieving the $Key and is unlocked only
588           after the value is removed, thus guaranteeing the value stored by
589           someone else isn't removed by us.
590
591       clear()
592           Clear all items from the cache
593
594           Note: If you're using callbacks, this has no effect on items in the
595           underlying data store. No delete callbacks are made
596
597       purge()
598           Clear all expired items from the cache
599
600           Note: If you're using callbacks, this has no effect on items in the
601           underlying data store. No delete callbacks are made, and no write
602           callbacks are made for the expired data
603
604       empty($OnlyExpired)
605           Empty all items from the cache, or if $OnlyExpired is true, only
606           expired items.
607
608           Note: If 'write_back' mode is enabled, any changed items are
609           written back to the underlying store. Expired items are written
610           back to the underlying store as well.
611
612       get_keys($Mode)
613           Get a list of keys/values held in the cache. May immediately be out
614           of date because of the shared access nature of the cache
615
616           If $Mode == 0, an array of keys is returned
617
618           If $Mode == 1, then an array of hashrefs, with 'key',
619           'last_access', 'expire_on' and 'flags' keys is returned
620
621           If $Mode == 2, then hashrefs also contain 'value' key
622
623       get_statistics($Clear)
624           Returns a two value list of (nreads, nreadhits). This only works if
625           you passed enable_stats in the constructor
626
627           nreads is the total number of read attempts done on the cache since
628           it was created
629
630           nreadhits is the total number of read attempts done on the cache
631           since it was created that found the key/value in the cache
632
633           If $Clear is true, the values are reset immediately after they are
634           retrieved
635
636       multi_get($PageKey, [ $Key1, $Key2, ... ])
637           The two multi_xxx routines act a bit differently to the other
638           routines. With the multi_get, you pass a separate PageKey value and
639           then multiple keys. The PageKey value is hashed, and that page
640           locked. Then that page is searched for each key. It returns a hash
641           ref of Key => Value items found in that page in the cache.
642
643           The main advantage of this is just a speed one, if you happen to
644           need to search for a lot of items on each call.
645
646           For instance, say you have users and a bunch of pieces of separate
647           information for each user. On a particular run, you need to
648           retrieve a sub-set of that information for a user. You could do
649           lots of get() calls, or you could use the 'username' as the page
650           key, and just use one multi_get() and multi_set() call instead.
651
652           A couple of things to note:
653
654           1.  This makes multi_get()/multi_set() and get()/set()
655               incompatible. Don't mix calls to the two, because you won't
656               find the data you're expecting
657
658           2.  The writeback and callback modes of operation do not work with
659               multi_get()/multi_set(). Don't attempt to use them together.
660
661       multi_set($PageKey, { $Key1 = $Value1, $Key2 => $Value2, ... }, [
662       \%Options ])>
663           Store specified key/value pair into cache
664

INTERNAL METHODS

666       _expunge_all($Mode, $WB)
667           Expunge all items from the cache
668
669           Expunged items (that have not expired) are written back to the
670           underlying store if write_back is enabled
671
672       _expunge_page($Mode, $WB, $Len)
673           Expunge items from the current page to make space for $Len bytes
674           key/value items
675
676           Expunged items (that have not expired) are written back to the
677           underlying store if write_back is enabled
678
679       _lock_page($Page)
680           Lock a given page in the cache, and return an object reference that
681           when DESTROYed, unlocks the page
682

INCOMPATIBLE CHANGES

684       •   From 1.15
685
686           •   Default share_file name is no-longer /tmp/sharefile, but
687               /tmp/sharefile-$pid-$time.  This ensures that different
688               runs/processes don't interfere with each other, but means you
689               may not connect up to the file you expect. You should be
690               choosing an explicit name in most cases.
691
692               On Unix systems, you can pass in the environment variable
693               TMPDIR to override the default directory of /tmp
694
695           •   The new option unlink_on_exit defaults to true if you pass a
696               filename for the share_file which doesn't already exist. This
697               means if you have one process that creates the file, and
698               another that expects the file to be there, by default it won't
699               be.
700
701               Otherwise the defaults seem sensible to cleanup unneeded share
702               files rather than leaving them around to accumulate.
703
704       •   From 1.29
705
706           •   Default share_file name is no longer /tmp/sharefile-$pid-$time
707               but /tmp/sharefile-$pid-$time-$random.
708
709       •   From 1.31
710
711           •   Before 1.31, if you were using raw_values => 0 mode, then the
712               write_cb would be called with raw frozen data, rather than the
713               thawed object.  From 1.31 onwards, it correctly calls write_cb
714               with the thawed object value (eg what was passed to the ->set()
715               call in the first place)
716
717       •   From 1.36
718
719           •   Before 1.36, an alarm(10) would be set before each attempt to
720               lock a page. The only purpose of this was to detect deadlocks,
721               which should only happen if the Cache::FastMmap code was buggy,
722               or a callback function in get_and_set() made another call into
723               Cache::FastMmap.
724
725               However this added unnecessary extra system calls for every
726               lookup, and for users using Time::HiRes, it could clobber any
727               existing alarms that had been set with sub-second resolution.
728
729               So this has now been made an optional feature via the
730               catch_deadlocks option passed to new.
731
732       •   From 1.52
733
734           •   The term expire_time was overloaded in the code to sometimes
735               mean a relative future time (e.g. as passed to new constructor)
736               or an absolute unix epoch (e.g. as returned from get_keys(2)).
737
738               To avoid this confusion, the code now uses expire_time to
739               always means a relative future time, and expire_on to mean an
740               absolute epoch time. You can use either as an optional argument
741               to a set() call.
742
743               Since expire_time was used in the constructor and is likely
744               more commonly used, I changed the result of get_keys(2) so it
745               now returns expire_on rather than expire_time.
746

SEE ALSO

748       MLDBM::Sync, IPC::MM, Cache::FileCache, Cache::SharedMemoryCache, DBI,
749       Cache::Mmap, BerkeleyDB
750
751       Latest news/details can also be found at:
752
753       <http://cpan.robm.fastmail.fm/cachefastmmap/>
754
755       Available on github at:
756
757       <https://github.com/robmueller/cache-fastmmap/>
758

AUTHOR

760       Rob Mueller <mailto:cpan@robm.fastmail.fm>
761
763       Copyright (C) 2003-2017 by FastMail Pty Ltd
764
765       This library is free software; you can redistribute it and/or modify it
766       under the same terms as Perl itself.
767
768
769
770perl v5.32.1                      2021-01-26                Cache::FastMmap(3)
Impressum