NAME

Cache::Adaptive - A Cache Engine with Adaptive Lifetime Control

SYNOPSIS

  use Cache::Adaptive;
  use Cache::FileCache;
  
  my $cache = Cache::Adaptive->new({
    backend     => Cache::FileCache->new({
      namespace => 'html_cache',
      max_size  => 10 * 1024 * 1024,
    }),
    expires_min => 3,
    expires_max => 60,
    check_load  => sub {
      my $entry = shift;
      int($entry->{process_time} * 2) - 1;
    },
  });
  
  ...
  
  print "Content-Type: text/html\n\n";
  print $cache->access({
    key     => $uri,
    builder => sub {
      # your HTML generation logic here
      $html;
    },
  });

DESCRIPTION

Cache::Adaptive is a cache engine with adaptive lifetime control. Cache lifetimes can be increased or decreased by any factor, e.g. load average, process time for building the cache entry, etc., through the definition of the check_load callback.

PROPERTIES

Cache::Adaptive recognizes following properties. The properties can be set though the constructor, or by calling the accessors.

backend

Backend storage to be used. Should be a Cache::Cache object. Note: do not use Cache::SizeAwareFileCache, since its get method might overwrite data saved by other processes. The update algorithm of Cache::Adaptive needs a reliable set method.

check_interval

Interval between calls to the check_load callback for each cache entry. Default is 0, meaning that check_load will be called every time the cache entry is being built.

check_load

User supplied callback for deciding the cache policy. If a positive number is returned, cache lifetime for the entry will be increased. If a negative number is returned, the lifetime will be decreased. If 0 is returned, the lifetime will not be modified. For detail, see the "DEFINING THE CACHE STRATEGY" section.

increase_factor, decrease_factor

Cache lifetime will be increased or decreased by applying either factor to current lifetime.

expires_min, expires_max

Minimal and maximal expiration times, in seconds.

log

An optional callback for logging.

purge_after

Seconds until per-entry information used for deciding caching algorithm will be purged. Defaults to expires_max * 2.

METHODS

new

See above.

access({ key => cache_key, builder => sub { ... } })

Returns the cached entry if possible, or builds the entry by calling the builder function, and optionally stores the build entry to cache.

DEFINING THE CACHE STRATEGY

A variety of cache strategies can be implemented by defining the check_load callback. Below are some examples.

CACHING HEAVY OPERATIONS

  my $cache = Cache::Adaptive->new({
    ...
    check_load => sub {
      my ($entry, $params) = @_;
      int($entry->{process_time} * 2) - 1;
    },
  });

Assume that the process time of each operation increases as the system becomes heavily loaded. Above code will start caching or increase cache lifetime if the process time for each operation takes more than a second. As more entries become cached, the system load will become lighter, leading to faster process times, and cache lifetimes will no more be increased. When the process time becomes smaller than 0.5 seconds, the cache lifetime will be decreased.

CACHING FREQUENTLY ACCESSED ENTRIES

  my $cache = Cache::Adaptive->new({
    ...
    check_interval => 60,
    check_load     => sub {
      my ($entry, $params) = @_;
      int($params->{load} * 4) - 1;
    },
  });

$params-{load}> contains $entry-{process_time}> divided by build frequency. The above code increases cache lifetime if the system is building the entry during more than 50% of its operation recently. Note that the system may be running multiple processes simultaneously. This value represents the real time, not CPU cycles that were actually spent for handling the operation.

UTILIZING CACHE UNDER HEAVY LOAD

  use BSD::Sysctl qw(sysctl);

  my $cache = Cache::Adaptive->new({
    ...
    check_interval => 60,
    check_load     => sub {
      my $load_avg = sysctl('vm.loadavg');
      int($load_avg->[0] * 2) - 1;
    },
  });

The example updates the cache lifetime by referring to the load average. The example should only work on BSD systems.

A COMPLEX EXAMPLE

  my $cache = Cache::Adaptive->new({
    ...
    check_interval => 60,
    check_load     => sub {
      my ($entry, $params) = @_;
      my $load_avg = sysctl('vm.loadavg');
      int($params{load} * 4 * $load_avg->[0] ** 2) - 1;
    },
  });

The example utilizes the cache for heavily accessed entries under heavy load.

UPDATES

For updates, see

  http://labs.cybozu.co.jp/blog/kazuho/
  http://labs.cybozu.co.jp/blog/kazuhoatwork/

AUTHOR

Copyright (c) 2007 Cybozu Labs, Inc. All rights reserved.

written by Kazuho Oku <kazuhooku@gmail.com>

CONTRIBUTORS

Toru Yamaguchi <zigorou@cpan.org>

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

cpanm Cache::Adaptive

perl -MCPAN -e shell
install Cache::Adaptive