view release on metacpan or  search on metacpan

Mmap.pm  view on Meta::CPAN

# $Id: Mmap.pm,v 1.15 2008/04/15 09:41:26 pmh Exp $

=head1 NAME

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

=head1 SYNOPSIS

  use Cache::Mmap;

  $cache=Cache::Mmap->new($filename,\%options);

  $val1=$cache->read($key1);
  $cache->write($key2,$val2);
  $cache->delete($key3);

=head1 DESCRIPTION

This module implements a shared data cache, using memory mapped files.
If routines are provided which interact with the underlying data, access to
the cache is completely transparent, and the module handles all the details of
refreshing cache contents, and updating underlying data, if necessary.

Cache entries are assigned to "buckets" within the cache file, depending on
the key. Within each bucket, entries are stored approximately in order of last
access, so that frequently accessed entries will move to the head of the
bucket, thus decreasing access time. Concurrent accesses to the same bucket are
prevented by file locking of the relevant section of the cache file.

=cut

package Cache::Mmap;

# Do we need to worry about UTF-8?
use constant has_utf8 => has_utf8 => $] >= 5.006_000;

use Carp qw(croak);
use DynaLoader();
use Exporter;
use Fcntl;
use IO::Seekable qw(SEEK_SET SEEK_END);
use Storable qw(freeze thaw);
use Symbol();
use integer;
use strict;
use vars qw(
  $VERSION @ISA
  @EXPORT_OK
);

$VERSION='0.11';
@ISA=qw(DynaLoader Exporter);
@EXPORT_OK=qw(CMM_keep_expired CMM_keep_expired_refresh);

__PACKAGE__->bootstrap($VERSION);

# Default cache options
my %def_options=(
  buckets => 13,	# Number of buckets
  bucketsize => 1024,	# Size of each bucket
  pagesize => 1024,	# Bucket alignment
  strings => 0,		# Store strings, rather than refs
  expiry => 0,		# Number of seconds to hold values, 0==forever
  context => undef,	# Context to pass to read and write subs
  permissions => 0600,	# Permissions for new file creation
# read => sub called as ($found,$val)/$val=$read->($key,$context)
  cachenegative  => 0,	# true:  Cache not-found values
			# false: Don't cache not-found values
# write => sub called as $write->($key,$oval,$context)
			# Leave out for no writing to underlying data
  writethrough => 1,	# true:  Write when value is added to cache
			# false: Write when value expires or is pushed out
# delete => sub called as $delete->($key,$oval,$context)
			# Leave out for no deleting of underlying data
);

# Bit positions for cache-level flags
use constant flag_strings => 0x0001;
# Names for cache-level flags
my %bool_opts=(
  strings => flag_strings,