MirOS Manual: Memoize::Expire(3p)


Memoize::Expire(3Perl Programmers Reference GuMemoize::Expire(3p)

NAME

     Memoize::Expire - Plug-in module for automatic expiration of
     memoized values

SYNOPSIS

       use Memoize;
       use Memoize::Expire;
       tie my %cache => 'Memoize::Expire',
                          LIFETIME => $lifetime,    # In seconds
                          NUM_USES => $n_uses;

       memoize 'function', SCALAR_CACHE => [HASH => \%cache ];

DESCRIPTION

     Memoize::Expire is a plug-in module for Memoize.  It allows
     the cached values for memoized functions to expire automati-
     cally.  This manual assumes you are already familiar with
     the Memoize module.  If not, you should study that manual
     carefully first, paying particular attention to the HASH
     feature.

     Memoize::Expire is a layer of software that you can insert
     in between Memoize itself and whatever underlying package
     implements the cache. The layer presents a hash variable
     whose values expire whenever they get too old, have been
     used too often, or both. You tell "Memoize" to use this for-
     getful hash as its cache instead of the default, which is an
     ordinary hash.

     To specify a real-time timeout, supply the "LIFETIME" option
     with a numeric value.  Cached data will expire after this
     many seconds, and will be looked up afresh when it expires.
     When a data item is looked up afresh, its lifetime is reset.

     If you specify "NUM_USES" with an argument of n, then each
     cached data item will be discarded and looked up afresh
     after the nth time you access it.  When a data item is
     looked up afresh, its number of uses is reset.

     If you specify both arguments, data will be discarded from
     the cache when either expiration condition holds.

     Memoize::Expire uses a real hash internally to store the
     cached data. You can use the "HASH" option to
     Memoize::Expire to supply a tied hash in place of the ordi-
     nary hash that Memoize::Expire will normally use.  You can
     use this feature to add Memoize::Expire as a layer in
     between a persistent disk hash and Memoize.  If you do this,
     you get a persistent disk cache whose entries expire
     automatically.  For example:

perl v5.8.8                2005-02-05                           1

Memoize::Expire(3Perl Programmers Reference GuMemoize::Expire(3p)

       #   Memoize
       #      |
       #   Memoize::Expire  enforces data expiration policy
       #      |
       #   DB_File  implements persistence of data in a disk file
       #      |
       #   Disk file

       use Memoize;
       use Memoize::Expire;
       use DB_File;

       # Set up persistence
       tie my %disk_cache => 'DB_File', $filename, O_CREAT|O_RDWR, 0666];

       # Set up expiration policy, supplying persistent hash as a target
       tie my %cache => 'Memoize::Expire',
                          LIFETIME => $lifetime,    # In seconds
                          NUM_USES => $n_uses,
                          HASH => \%disk_cache;

       # Set up memoization, supplying expiring persistent hash for cache
       memoize 'function', SCALAR_CACHE => [ HASH => \%cache ];

INTERFACE

     There is nothing special about Memoize::Expire.  It is just
     an example.  If you don't like the policy that it imple-
     ments, you are free to write your own expiration policy
     module that implements whatever policy you desire.  Here is
     how to do that.  Let us suppose that your module will be
     named MyExpirePolicy.

     Short summary: You need to create a package that defines
     four methods:

     TIEHASH
         Construct and return cache object.

     EXISTS
         Given a function argument, is the corresponding function
         value in the cache, and if so, is it fresh enough to
         use?

     FETCH
         Given a function argument, look up the corresponding
         function value in the cache and return it.

     STORE
         Given a function argument and the corresponding function
         value, store them into the cache.

     CLEAR

perl v5.8.8                2005-02-05                           2

Memoize::Expire(3Perl Programmers Reference GuMemoize::Expire(3p)

         (Optional.)  Flush the cache completely.

     The user who wants the memoization cache to be expired
     according to your policy will say so by writing

       tie my %cache => 'MyExpirePolicy', args...;
       memoize 'function', SCALAR_CACHE => [HASH => \%cache];

     This will invoke "MyExpirePolicy->TIEHASH(args)".
     MyExpirePolicy::TIEHASH should do whatever is appropriate to
     set up the cache, and it should return the cache object to
     the caller.

     For example, MyExpirePolicy::TIEHASH might create an object
     that contains a regular Perl hash (which it will to store
     the cached values) and some extra information about the
     arguments and how old the data is and things like that.  Let
     us call this object `C'.

     When Memoize needs to check to see if an entry is in the
     cache already, it will invoke "C->EXISTS(key)".  "key" is
     the normalized function argument.  MyExpirePolicy::EXISTS
     should return 0 if the key is not in the cache, or if it has
     expired, and 1 if an unexpired value is in the cache.  It
     should not return "undef", because there is a bug in some
     versions of Perl that will cause a spurious FETCH if the
     EXISTS method returns "undef".

     If your EXISTS function returns true, Memoize will try to
     fetch the cached value by invoking "C->FETCH(key)".
     MyExpirePolicy::FETCH should return the cached value.  Oth-
     erwise, Memoize will call the memoized function to compute
     the appropriate value, and will store it into the cache by
     calling "C->STORE(key, value)".

     Here is a very brief example of a policy module that expires
     each cache item after ten seconds.

             package Memoize::TenSecondExpire;

             sub TIEHASH {
               my ($package, %args) = @_;
               my $cache = $args{HASH} || {};
               bless $cache => $package;
             }

perl v5.8.8                2005-02-05                           3

Memoize::Expire(3Perl Programmers Reference GuMemoize::Expire(3p)

             sub EXISTS {
               my ($cache, $key) = @_;
               if (exists $cache->{$key} &&
                   $cache->{$key}{EXPIRE_TIME} > time) {
                 return 1
               } else {
                 return 0;  # Do NOT return `undef' here.
               }
             }

             sub FETCH {
               my ($cache, $key) = @_;
               return $cache->{$key}{VALUE};
             }

             sub STORE {
               my ($cache, $key, $newvalue) = @_;
               $cache->{$key}{VALUE} = $newvalue;
               $cache->{$key}{EXPIRE_TIME} = time + 10;
             }

     To use this expiration policy, the user would say

             use Memoize;
             tie my %cache10sec => 'Memoize::TenSecondExpire';
             memoize 'function', SCALAR_CACHE => [HASH => \%cache10sec];

     Memoize would then call "function" whenever a cached value
     was entirely absent or was older than ten seconds.

     You should always support a "HASH" argument to "TIEHASH"
     that ties the underlying cache so that the user can specify
     that the cache is also persistent or that it has some other
     interesting semantics.  The example above demonstrates how
     to do this, as does "Memoize::Expire".

ALTERNATIVES

     Brent Powers has a "Memoize::ExpireLRU" module that was
     designed to work with Memoize and provides expiration of
     least-recently-used data. The cache is held at a fixed
     number of entries, and when new data comes in, the least-
     recently used data is expired.  See
     <http://search.cpan.org/search?mode=module&query=ExpireLRU>.

     Joshua Chamas's Tie::Cache module may be useful as an
     expiration manager.  (If you try this, let me know how it
     works out.)

     If you develop any useful expiration managers that you think
     should be distributed with Memoize, please let me know.

perl v5.8.8                2005-02-05                           4

Memoize::Expire(3Perl Programmers Reference GuMemoize::Expire(3p)

CAVEATS

     This module is experimental, and may contain bugs.  Please
     report bugs to the address below.

     Number-of-uses is stored as a 16-bit unsigned integer, so
     can't exceed 65535.

     Because of clock granularity, expiration times may occur up
     to one second sooner than you expect.  For example, suppose
     you store a value with a lifetime of ten seconds, and you
     store it at 12:00:00.998 on a certain day.  Memoize will
     look at the clock and see 12:00:00.  Then 9.01 seconds
     later, at 12:00:10.008 you try to read it back.  Memoize
     will look at the clock and see 12:00:10 and conclude that
     the value has expired.  This will probably not occur if you
     have "Time::HiRes" installed.

AUTHOR

     Mark-Jason Dominus (mjd-perl-memoize+@plover.com)

     Mike Cariaso provided valuable insight into the best way to
     solve this problem.

SEE ALSO

     perl(1)

     The Memoize man page.

     http://www.plover.com/~mjd/perl/Memoize/  (for news and
     updates)

     I maintain a mailing list on which I occasionally announce
     new versions of Memoize.  The list is for announcements
     only, not discussion.  To join, send an empty message to
     mjd-perl-memoize-request@Plover.com.

perl v5.8.8                2005-02-05                           5

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.