view release on metacpan or  search on metacpan

Mmap.pm  view on Meta::CPAN

If true, cache entries are treated as strings, rather than references. This
will help performance for string-only caches, as no time will be taken to
serialize cache entries.

=item expiry (0)

If non-zero, sets the length of time, in seconds, which cache entries are
considered valid. A new entry will be fetched from the underlying data if
an expired cache entry would otherwise have been returned.

=item context (undef)

This value is passed to the read/write/delete routines below, to provide
context. This will typically be a database handle, used to fetch data from.

=item read (undef)

Provides a code reference to a routine which will fetch entries from the
underlying data. Called as C<$read-E<gt>($key,$context)>, this routine should
return a list C<($found,$value)>, where C<$found> is true if the entry could
be found in the underlying data, and C<$value> is the value to cache.

If the routine only returns a single scalar, that will be taken as
the value, and C<$found> will be set to true if the value is defined.

If this routine is not provided, only values already in the cache will ever
be returned.

There are currently two special values of C<$found> which cause slightly
different behaviour. These are constants which may be imported in the
C<use> statement.

=over 4

=item C<Cache::Mmap::CMM_keep_expired>

Use the previously cached value, even if it has expired. This is useful if
the underlying data source has become unavailable for some reason. Note that
even though the value returned will be ignored in this case, it must be
returned to avoid C<$found> being interpreted as a single scalar:

  return (Cache::Mmap::CMM_keep_expired, undef);

=item C<Cache::Mmap::CMM_keep_expired_refresh>

This causes the same behaviour as C<CMM_keep_expired>, but the cache entry's
expiry time will be reset as if a value had been successfully read from the
underlying data.

=back

=item cachenegative (0)

If true, even unsuccessful fetches from the underlying data are cached. This
can be useful to only search the underlying data once for each required key.

=item write (undef)

Provides a code reference to a routine which will write cache entries into the
underlying data. This routine will be called by write(), to synchronise the
underlying data with the cache. Called as C<$write-E<gt>($key,$val,$context)>.
If the routine is not provided, the underlying data will not be synchronised
after cache writes.

=item writethrough (1)

If true, the C<write> routine above will be called as soon as
write() is called. This provides immediate synchronisation of
underlying data and cache contents.

If false, the C<write> routine will
be called for each cache entry which no longer fits in its bucket after a
cache read or write. This provides a write-as-necessary behaviour, which may
be more efficient than the writethrough behaviour. However, only data fetched
through the cache will reflect these changes.

=item delete (undef)

Provides a code reference to a routine which will delete items from the
underlying data. This routine will be called by delete(),
to synchronise the underlying data with the cache. Called as
C<$delete-E<gt>($key,$cval,$context)>, where C<$cval> is the value
currently stored in the cache. If this routine is not provided, entries
deleted from the cache have no effect on the underlying data.

=back

An alternative to supplying a C<write> routine, is to call
delete() after updating the underlying data. Note however, that
in the case of databases, this should be done after committing the update, so
that a concurrent process doesn't reload the cache between being the entry
being deleted, and the database updates being committed.

=cut

sub new{
  my($class,$filename,$options)=@_;
  my $self={
    %def_options,
    %{$options || {}},
  };

  # Check options for sensible values
  foreach(qw(buckets bucketsize pagesize permissions)){
    defined($self->{$_}) && $self->{$_}=~/^[1-9]\d*$/s
      or croak "'$_' option for $class must be a positive integer";
  }
  $self->{pagesize}>=$maxheadsize
    or croak "'pagesize' option for $class must be at least $maxheadsize";
  foreach(qw(read write delete)){
    !$self->{$_} || ref $self->{$_} eq 'CODE'
      or croak "'$_' option for $class must be a CODE ref or empty";
  }

  # Align bucketsize
  {
    no integer;
    my $n_pages=$self->{bucketsize}/$self->{pagesize};
    if((my $i_pages=int $n_pages)!=$n_pages){
      $self->{bucketsize}=($i_pages+1)*$self->{pagesize};
    }
  }

  # Try to open a file
  my $fh=Symbol::gensym;
  sysopen($fh,$filename,O_RDWR|O_CREAT,$self->{permissions})
    or croak "Can't open cache file $filename: $!";

  # Create cache object
  bless $self,$class;
  $self->{_filename}=$filename;
  $self->{_fh}=$fh;

  # Set options
  $self->_set_options;

  $self;
}

=back