Memoize::Expire(3pm)

1Memoize::Expire(3pm)   Perl Programmers Reference Guide   Memoize::Expire(3pm)
2
3
4

NAME

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

SYNOPSIS

10         use Memoize;
11         use Memoize::Expire;
12         tie my %cache => 'Memoize::Expire',
13                            LIFETIME => $lifetime,    # In seconds
14                            NUM_USES => $n_uses;
15
16         memoize 'function', SCALAR_CACHE => [HASH => \%cache ];
17

DESCRIPTION

19       Memoize::Expire is a plug-in module for Memoize.  It allows the cached
20       values for memoized functions to expire automatically.  This manual
21       assumes you are already familiar with the Memoize module.  If not, you
22       should study that manual carefully first, paying particular attention
23       to the HASH feature.
24
25       Memoize::Expire is a layer of software that you can insert in between
26       Memoize itself and whatever underlying package implements the cache.
27       The layer presents a hash variable whose values expire whenever they
28       get too old, have been used too often, or both. You tell "Memoize" to
29       use this forgetful hash as its cache instead of the default, which is
30       an ordinary hash.
31
32       To specify a real-time timeout, supply the "LIFETIME" option with a
33       numeric value.  Cached data will expire after this many seconds, and
34       will be looked up afresh when it expires.  When a data item is looked
35       up afresh, its lifetime is reset.
36
37       If you specify "NUM_USES" with an argument of n, then each cached data
38       item will be discarded and looked up afresh after the nth time you
39       access it.  When a data item is looked up afresh, its number of uses is
40       reset.
41
42       If you specify both arguments, data will be discarded from the cache
43       when either expiration condition holds.
44
45       Memoize::Expire uses a real hash internally to store the cached data.
46       You can use the "HASH" option to Memoize::Expire to supply a tied hash
47       in place of the ordinary hash that Memoize::Expire will normally use.
48       You can use this feature to add Memoize::Expire as a layer in between a
49       persistent disk hash and Memoize.  If you do this, you get a persistent
50       disk cache whose entries expire automatically.  For example:
51
52         #   Memoize
53         #      |
54         #   Memoize::Expire  enforces data expiration policy
55         #      |
56         #   DB_File  implements persistence of data in a disk file
57         #      |
58         #   Disk file
59
60         use Memoize;
61         use Memoize::Expire;
62         use DB_File;
63
64         # Set up persistence
65         tie my %disk_cache => 'DB_File', $filename, O_CREAT|O_RDWR, 0666];
66
67         # Set up expiration policy, supplying persistent hash as a target
68         tie my %cache => 'Memoize::Expire',
69                            LIFETIME => $lifetime,    # In seconds
70                            NUM_USES => $n_uses,
71                            HASH => \%disk_cache;
72
73         # Set up memoization, supplying expiring persistent hash for cache
74         memoize 'function', SCALAR_CACHE => [ HASH => \%cache ];
75

INTERFACE

77       There is nothing special about Memoize::Expire.  It is just an example.
78       If you don't like the policy that it implements, you are free to write
79       your own expiration policy module that implements whatever policy you
80       desire.  Here is how to do that.  Let us suppose that your module will
81       be named MyExpirePolicy.
82
83       Short summary: You need to create a package that defines four methods:
84
85        TIEHASH
86           Construct and return cache object.
87
88        EXISTS
89           Given a function argument, is the corresponding function value in
90           the cache, and if so, is it fresh enough to use?
91
92        FETCH
93           Given a function argument, look up the corresponding function value
94           in the cache and return it.
95
96        STORE
97           Given a function argument and the corresponding function value,
98           store them into the cache.
99
100        CLEAR
101           (Optional.)  Flush the cache completely.
102
103       The user who wants the memoization cache to be expired according to
104       your policy will say so by writing
105
106         tie my %cache => 'MyExpirePolicy', args...;
107         memoize 'function', SCALAR_CACHE => [HASH => \%cache];
108
109       This will invoke "MyExpirePolicy->TIEHASH(args)".
110       MyExpirePolicy::TIEHASH should do whatever is appropriate to set up the
111       cache, and it should return the cache object to the caller.
112
113       For example, MyExpirePolicy::TIEHASH might create an object that
114       contains a regular Perl hash (which it will to store the cached values)
115       and some extra information about the arguments and how old the data is
116       and things like that.  Let us call this object `C'.
117
118       When Memoize needs to check to see if an entry is in the cache already,
119       it will invoke "C->EXISTS(key)".  "key" is the normalized function
120       argument.  MyExpirePolicy::EXISTS should return 0 if the key is not in
121       the cache, or if it has expired, and 1 if an unexpired value is in the
122       cache.  It should not return "undef", because there is a bug in some
123       versions of Perl that will cause a spurious FETCH if the EXISTS method
124       returns "undef".
125
126       If your EXISTS function returns true, Memoize will try to fetch the
127       cached value by invoking "C->FETCH(key)".  MyExpirePolicy::FETCH should
128       return the cached value.  Otherwise, Memoize will call the memoized
129       function to compute the appropriate value, and will store it into the
130       cache by calling "C->STORE(key, value)".
131
132       Here is a very brief example of a policy module that expires each cache
133       item after ten seconds.
134
135               package Memoize::TenSecondExpire;
136
137               sub TIEHASH {
138                 my ($package, %args) = @_;
139                 my $cache = $args{HASH} || {};
140                 bless $cache => $package;
141               }
142
143               sub EXISTS {
144                 my ($cache, $key) = @_;
145                 if (exists $cache->{$key} &&
146                     $cache->{$key}{EXPIRE_TIME} > time) {
147                   return 1
148                 } else {
149                   return 0;  # Do NOT return `undef' here.
150                 }
151               }
152
153               sub FETCH {
154                 my ($cache, $key) = @_;
155                 return $cache->{$key}{VALUE};
156               }
157
158               sub STORE {
159                 my ($cache, $key, $newvalue) = @_;
160                 $cache->{$key}{VALUE} = $newvalue;
161                 $cache->{$key}{EXPIRE_TIME} = time + 10;
162               }
163
164       To use this expiration policy, the user would say
165
166               use Memoize;
167               tie my %cache10sec => 'Memoize::TenSecondExpire';
168               memoize 'function', SCALAR_CACHE => [HASH => \%cache10sec];
169
170       Memoize would then call "function" whenever a cached value was entirely
171       absent or was older than ten seconds.
172
173       You should always support a "HASH" argument to "TIEHASH" that ties the
174       underlying cache so that the user can specify that the cache is also
175       persistent or that it has some other interesting semantics.  The
176       example above demonstrates how to do this, as does "Memoize::Expire".
177
178       Another sample module, Memoize::Saves, is available in a separate
179       distribution on CPAN.  It implements a policy that allows you to
180       specify that certain function values would always be looked up afresh.
181       See the documentation for details.
182

ALTERNATIVES

184       Brent Powers has a "Memoize::ExpireLRU" module that was designed to
185       work with Memoize and provides expiration of least-recently-used data.
186       The cache is held at a fixed number of entries, and when new data comes
187       in, the least-recently used data is expired.  See
188       <http://search.cpan.org/search?mode=module&query=ExpireLRU>.
189
190       Joshua Chamas's Tie::Cache module may be useful as an expiration
191       manager.  (If you try this, let me know how it works out.)
192
193       If you develop any useful expiration managers that you think should be
194       distributed with Memoize, please let me know.
195

CAVEATS

197       This module is experimental, and may contain bugs.  Please report bugs
198       to the address below.
199
200       Number-of-uses is stored as a 16-bit unsigned integer, so can't exceed
201       65535.
202
203       Because of clock granularity, expiration times may occur up to one
204       second sooner than you expect.  For example, suppose you store a value
205       with a lifetime of ten seconds, and you store it at 12:00:00.998 on a
206       certain day.  Memoize will look at the clock and see 12:00:00.  Then
207       9.01 seconds later, at 12:00:10.008 you try to read it back.  Memoize
208       will look at the clock and see 12:00:10 and conclude that the value has
209       expired.  This will probably not occur if you have "Time::HiRes"
210       installed.
211

AUTHOR

213       Mark-Jason Dominus (mjd-perl-memoize+@plover.com)
214
215       Mike Cariaso provided valuable insight into the best way to solve this
216       problem.
217