NAME
Cache::FastMmap - Uses an mmap'ed file to act as a shared memory interprocess cache
SYNOPSIS
use Cache::FastMmap;
# Uses vaguely sane defaults
$Cache = Cache::FastMmap->new();
$Cache->set($Key, $Value);
$Value = $Cache->get($Key);ABSTRACT
A shared memory cache through an mmap'ed file. It's core is written in C for performance. It uses fcntl locking to ensure multiple processes can safely access the cache at the same time. It uses a basic LRU algorithm to keep the most used entries in the cache.
DESCRIPTION
In multi-process environments (eg mod_perl, forking daemons, etc), it's common to want to cache information, but have that cache shared between processes. Many solutions already exist, and may suit your situation better:
MLDBM::Sync - acts as a database, data is not automatically expired, slow
IPC::MM - hash implementation is broken, data is not automatically expired, slow
Cache::FileCache - lots of features, slow
Cache::SharedMemoryCache - lots of features, VERY slow. Uses IPC::ShareLite which freeze/thaws ALL data at each read/write
DBI - use your favourite RDBMS. can perform well, need a DB server running. very global. socket connection latency
Cache::Mmap - similar to this module, in pure perl. slows down with larger pages
In the case I was working on, I needed:
Automatic expiry and space management
Very fast access to lots of small items
Which is why I developed this module. It tries to be quite efficient through a number of means:
Core code is written in C for performance
It uses multiple pages within a file, and uses Fcntl to only lock a page at a time to reduce contention when multiple processes access the cache.
It uses a dual level hashing system (hash to find page, then hash within each page to find a slot) to make most get calls O(1) and fast
On each set, if there are slots and page space available, only the slot has to be updated and the data written at the end of the used data space. If either runs out, a re-organisation of the page is performed to create new slots/space which is done in an efficient way
The class also supports read-through, and write-back or write-through callbacks to access the real data if it's not in the cache, meaning that code like this:
my $Value = $Cache->get($Key);
if (!defined $Value) {
$Value = $RealDataSource->get($Key);
$Cache->set($Key, $Value)
}Isn't required, you instead specify in the constructor:
Cache::FastMmap->new(
...
context => $RealDataSourceHandle,
read_cb => sub { $_[0]->get($_[1]) },
write_cb => sub { $_[0]->set($_[1], $_[2]) },
);And then:
my $Value = $Cache->get($Key);
$Cache->set($Key, $NewValue);Will just work and will be read/written to the underlying data source as needed automatically
PERFORMANCE
If you're storing relatively large and complex structures into the cache, then you're limited by the speed of the Storable module. If you're storing simple structures, or raw data, then Cache::FastMmap has noticeable performance improvements.
See http://cpan.robm.fastmail.fm/cache_perf.html for some comparisons to other modules.
METHODS
- new(%Opts)
-
Create a new Cache::FastMmap object.
Basic global parameters are:
share_file
File to mmap for sharing of data (default: /tmp/sharefile)
init_file
Clear any existing values and re-initialise file. Useful to do in a parent that forks off children to ensure that file is empty at the start (default: 0)
Note: This is quite important to do in the parent to ensure a consistent file structure. The shared file is not perfectly transaction safe, and so if a child is killed at the wrong instant, it might leave the the cache file in an inconsistent state.
raw_values
Store values as raw binary data rather than using Storable to free/thaw data structures (default: 0)
expire_time
Maximum time to hold values in the cache in seconds. A value of 0 means does no explicit expiry time, and values are expired only based on LRU usage. Can be expressed as 1m, 1h, 1d for minutes/hours/days respectively. (default: 0)
You may specify the cache size as:
cache_size
Size of cache. Can be expresses as 1k, 1m for kilobytes or megabytes respectively. Automatically guesses page size/page count values.
Or specify explicit page size/page count values. If none of these are specified, the values page_size = 64k and num_pages = 89 are used.
page_size
Size of each page. Must be a power of 2 between 4k and 1024k. If not, is rounded to the nearest value.
num_pages
Number of pages. Should be a prime number for best hashing
The cache allows the use of callbacks for reading/writing data to an underlying data store.
context
Opaque reference passed as the first parameter to any callback function if specified
read_cb
Callback to read data from the underlying data store. Called as:
$read_cb->($context, $Key)Should return the value to use. This value will be saved in the cache for future retrievals. Return undef if there is no value for the given key
write_cb
Callback to write data to the underlying data store. Called as:
$write_cb->($context, $Key, $Value)In 'write_through' mode, it's always called as soon as a set(...) is called on the Cache::FastMmap class. In 'write_back' mode, it's called when a value is expunged from the cache if it's been changed by a set(...) rather than read from the underlying store with the read_cb above.
Note: Expired items do not result in the write_cb being called if 'write_back' caching is enabled. The expired items are just thrown away
Also remember that write_cb may be called in a different process to the one that placed the data in the cache in the first place
delete_cb
Callback to delete data from the underlying data store. Called as:
$delete_cb->($context, $Key)Called as soon as remove(...) is called on the Cache::FastMmap class
cache_not_found
If set to true, then if the read_cb is called and it returns undef to say nothing was found, then that information is stored in the cache, so that next time a get(...) is called on that key, undef is returned immediately rather than again calling the read_cb
write_action
Either 'write_back' or 'write_through'. (default: write_through)
empty_on_exit
When you have 'write_back' mode enabled, then you really want to make sure all values from the cache are expunged when your program exits so any changes are written back. This is a bit tricky, because we don't know if you're in a child, so you must ensure that the parent process either explicitly calls empty() or that this flag is set to true when the parent connects to the cache, and false in all the children
- get($Key)
-
Search cache for given Key. Returns undef if not found. If read_cb specified and not found, calls the callback to try and find the value for the key, and if found (or 'cache_not_found' is set), stores it into the cache and returns the found value
- set($Key, $Value)
-
Store specified key/value pair into cache
- remove($Key)
-
Delete the given key from the cache
- clear()
-
Clear all items from the cache
Note: If you're using callbacks, this has no effect on items in the underlying data store. No delete callbacks are made
- purge()
-
Clear all expired items from the cache
Note: If you're using callbacks, this has no effect on items in the underlying data store. No delete callbacks are made, and no write callbacks are made for the expired data
- empty()
-
Empty all items from the cache.
Note: If 'write_back' mode is enabled, any changed items are written back to the underlying store. Expired items are not written back to the underlying store
- get_keys($Mode)
-
Get a list of keys/values held in the cache. May immediately be out of date because of the shared access nature of the cache
If $Mode == 0, an array of keys is returned
If $Mode == 1, then an array of hashrefs, with 'key', 'last_access', 'expire_time' and 'flags' keys is returned
If $Mode == 2, then hashrefs also contain 'value' key
INTERNAL METHODS
- _expunge_all($Mode)
-
Expunge all items from the cache
Expunged items (that have not expired) are written back to the underlying store if write_back is enabled
- _expunge_page($Mode, $WB, $Len)
-
Expunge items from the current page to make space for $Len bytes key/value items
Expunged items (that have not expired) are written back to the underlying store if write_back is enabled
SEE ALSO
MLDBM::Sync, IPC::MM, Cache::FileCache, Cache::SharedMemoryCache, DBI, Cache::Mmap
Latest news/details can also be found at:
http://cpan.robm.fastmail.fm/cachefastmmap/
AUTHOR
Rob Mueller <cpan@robm.fastmail.fm>
COPYRIGHT AND LICENSE
Copyright (C) 2003 by FastMail IP Partners
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.