1Memoize::Expire(3pm) Perl Programmers Reference Guide Memoize::Expire(3pm)
2
6 Memoize::Expire - Plug-in module for automatic expiration of memoized
7 values
8
10 use Memoize;
11 use Memoize::Expire;
12 tie my %cache => 'Memoize::Expire',
13 LIFETIME => $lifetime, # In seconds
14 NUM_USES => $n_uses;
15 memoize 'function', SCALAR_CACHE => [HASH => \%cache ];
17
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 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 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 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 If you specify both arguments, data will be discarded from the cache
43 when either expiration condition holds.
44 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 # 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 use Memoize;
61 use Memoize::Expire;
62 use DB_File;
63 # Set up persistence
65 tie my %disk_cache => 'DB_File', $filename, O_CREAT|O_RDWR, 0666];
66 # 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 # Set up memoization, supplying expiring persistent hash for cache
74 memoize 'function', SCALAR_CACHE => [ HASH => \%cache ];
75
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 Short summary: You need to create a package that defines four methods:
84 TIEHASH
86 Construct and return cache object.
87 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 FETCH
93 Given a function argument, look up the corresponding function value
94 in the cache and return it.
95 STORE
97 Given a function argument and the corresponding function value,
98 store them into the cache.
99 CLEAR
101 (Optional.) Flush the cache completely.
102 The user who wants the memoization cache to be expired according to
104 your policy will say so by writing
105 tie my %cache => 'MyExpirePolicy', args...;
107 memoize 'function', SCALAR_CACHE => [HASH => \%cache];
108 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 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 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 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 Here is a very brief example of a policy module that expires each cache
133 item after ten seconds.
134 package Memoize::TenSecondExpire;
136 sub TIEHASH {
138 my ($package, %args) = @_;
139 my $cache = $args{HASH} || {};
140 bless $cache => $package;
141 }
142 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 sub FETCH {
154 my ($cache, $key) = @_;
155 return $cache->{$key}{VALUE};
156 }
157 sub STORE {
159 my ($cache, $key, $newvalue) = @_;
160 $cache->{$key}{VALUE} = $newvalue;
161 $cache->{$key}{EXPIRE_TIME} = time + 10;
162 }
163 To use this expiration policy, the user would say
165 use Memoize;
167 tie my %cache10sec => 'Memoize::TenSecondExpire';
168 memoize 'function', SCALAR_CACHE => [HASH => \%cache10sec];
169 Memoize would then call "function" whenever a cached value was entirely
171 absent or was older than ten seconds.
172 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 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
184 Brent Powers has a Memoize::ExpireLRU module that was designed to work
185 with Memoize and provides expiration of least-recently-used data. The
186 cache is held at a fixed number of entries, and when new data comes in,
187 the least-recently used data is expired.
188 Joshua Chamas's Tie::Cache module may be useful as an expiration
190 manager. (If you try this, let me know how it works out.)
191 If you develop any useful expiration managers that you think should be
193 distributed with Memoize, please let me know.
194
196 This module is experimental, and may contain bugs. Please report bugs
197 to the address below.
198 Number-of-uses is stored as a 16-bit unsigned integer, so can't exceed
200 65535.
201 Because of clock granularity, expiration times may occur up to one
203 second sooner than you expect. For example, suppose you store a value
204 with a lifetime of ten seconds, and you store it at 12:00:00.998 on a
205 certain day. Memoize will look at the clock and see 12:00:00. Then
206 9.01 seconds later, at 12:00:10.008 you try to read it back. Memoize
207 will look at the clock and see 12:00:10 and conclude that the value has
208 expired. This will probably not occur if you have "Time::HiRes"
209 installed.
210
212 Mark-Jason Dominus
213 Mike Cariaso provided valuable insight into the best way to solve this
215 problem.
216
218 perl(1)
219 The Memoize man page.
221perl v5.38.2 2023-11-30 Memoize::Expire(3pm)