Debian Codegraph @

upstream/debian-unstable/man3/Memoize::Expire.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Memoize::Expire 3perl"
58 .TH Memoize::Expire 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Memoize::Expire \- Plug\-in module for automatic expiration of memoized values
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 5
68 \& use Memoize;
69 \& use Memoize::Expire;
70 \& tie my %cache => \*(AqMemoize::Expire\*(Aq,
71 \& LIFETIME => $lifetime, # In seconds
72 \& NUM_USES => $n_uses;
73 \&
74 \& memoize \*(Aqfunction\*(Aq, SCALAR_CACHE => [HASH => \e%cache ];
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 Memoize::Expire is a plug-in module for Memoize. It allows the cached
79 values for memoized functions to expire automatically. This manual
80 assumes you are already familiar with the Memoize module. If not, you
81 should study that manual carefully first, paying particular attention
82 to the HASH feature.
83 .PP
84 Memoize::Expire is a layer of software that you can insert in between
85 Memoize itself and whatever underlying package implements the cache.
86 The layer presents a hash variable whose values expire whenever they
87 get too old, have been used too often, or both. You tell \f(CW\*(C`Memoize\*(C'\fR to
88 use this forgetful hash as its cache instead of the default, which is
89 an ordinary hash.
90 .PP
91 To specify a real-time timeout, supply the \f(CW\*(C`LIFETIME\*(C'\fR option with a
92 numeric value. Cached data will expire after this many seconds, and
93 will be looked up afresh when it expires. When a data item is looked
94 up afresh, its lifetime is reset.
95 .PP
96 If you specify \f(CW\*(C`NUM_USES\*(C'\fR with an argument of \fIn\fR, then each cached
97 data item will be discarded and looked up afresh after the \fIn\fRth time
98 you access it. When a data item is looked up afresh, its number of
99 uses is reset.
100 .PP
101 If you specify both arguments, data will be discarded from the cache
102 when either expiration condition holds.
103 .PP
104 Memoize::Expire uses a real hash internally to store the cached data.
105 You can use the \f(CW\*(C`HASH\*(C'\fR option to Memoize::Expire to supply a tied
106 hash in place of the ordinary hash that Memoize::Expire will normally
107 use. You can use this feature to add Memoize::Expire as a layer in
108 between a persistent disk hash and Memoize. If you do this, you get a
109 persistent disk cache whose entries expire automatically. For
110 example:
111 .PP
112 .Vb 7
113 \& # Memoize
114 \& # |
115 \& # Memoize::Expire enforces data expiration policy
116 \& # |
117 \& # DB_File implements persistence of data in a disk file
118 \& # |
119 \& # Disk file
120 \&
121 \& use Memoize;
122 \& use Memoize::Expire;
123 \& use DB_File;
124 \&
125 \& # Set up persistence
126 \& tie my %disk_cache => \*(AqDB_File\*(Aq, $filename, O_CREAT|O_RDWR, 0666];
127 \&
128 \& # Set up expiration policy, supplying persistent hash as a target
129 \& tie my %cache => \*(AqMemoize::Expire\*(Aq,
130 \& LIFETIME => $lifetime, # In seconds
131 \& NUM_USES => $n_uses,
132 \& HASH => \e%disk_cache;
133 \&
134 \& # Set up memoization, supplying expiring persistent hash for cache
135 \& memoize \*(Aqfunction\*(Aq, SCALAR_CACHE => [ HASH => \e%cache ];
136 .Ve
137 .SH INTERFACE
138 .IX Header "INTERFACE"
139 There is nothing special about Memoize::Expire. It is just an
140 example. If you don't like the policy that it implements, you are
141 free to write your own expiration policy module that implements
142 whatever policy you desire. Here is how to do that. Let us suppose
143 that your module will be named MyExpirePolicy.
144 .PP
145 Short summary: You need to create a package that defines four methods:
146 .IP " TIEHASH" 4
147 .IX Item " TIEHASH"
148 Construct and return cache object.
149 .IP " EXISTS" 4
150 .IX Item " EXISTS"
151 Given a function argument, is the corresponding function value in the
152 cache, and if so, is it fresh enough to use?
153 .IP " FETCH" 4
154 .IX Item " FETCH"
155 Given a function argument, look up the corresponding function value in
156 the cache and return it.
157 .IP " STORE" 4
158 .IX Item " STORE"
159 Given a function argument and the corresponding function value, store
160 them into the cache.
161 .IP " CLEAR" 4
162 .IX Item " CLEAR"
163 (Optional.) Flush the cache completely.
164 .PP
165 The user who wants the memoization cache to be expired according to
166 your policy will say so by writing
167 .PP
168 .Vb 2
169 \& tie my %cache => \*(AqMyExpirePolicy\*(Aq, args...;
170 \& memoize \*(Aqfunction\*(Aq, SCALAR_CACHE => [HASH => \e%cache];
171 .Ve
172 .PP
173 This will invoke \f(CW\*(C`MyExpirePolicy\->TIEHASH(args)\*(C'\fR.
174 MyExpirePolicy::TIEHASH should do whatever is appropriate to set up
175 the cache, and it should return the cache object to the caller.
176 .PP
177 For example, MyExpirePolicy::TIEHASH might create an object that
178 contains a regular Perl hash (which it will to store the cached
179 values) and some extra information about the arguments and how old the
180 data is and things like that. Let us call this object \fR\f(CI\*(C`C\*(C'\fR\fI\fR.
181 .PP
182 When Memoize needs to check to see if an entry is in the cache
183 already, it will invoke \f(CW\*(C`C\->EXISTS(key)\*(C'\fR. \f(CW\*(C`key\*(C'\fR is the normalized
184 function argument. MyExpirePolicy::EXISTS should return 0 if the key
185 is not in the cache, or if it has expired, and 1 if an unexpired value
186 is in the cache. It should \fInot\fR return \f(CW\*(C`undef\*(C'\fR, because there is a
187 bug in some versions of Perl that will cause a spurious FETCH if the
188 EXISTS method returns \f(CW\*(C`undef\*(C'\fR.
189 .PP
190 If your EXISTS function returns true, Memoize will try to fetch the
191 cached value by invoking \f(CW\*(C`C\->FETCH(key)\*(C'\fR. MyExpirePolicy::FETCH should
192 return the cached value. Otherwise, Memoize will call the memoized
193 function to compute the appropriate value, and will store it into the
194 cache by calling \f(CW\*(C`C\->STORE(key, value)\*(C'\fR.
195 .PP
196 Here is a very brief example of a policy module that expires each
197 cache item after ten seconds.
198 .PP
199 .Vb 1
200 \& package Memoize::TenSecondExpire;
201 \&
202 \& sub TIEHASH {
203 \& my ($package, %args) = @_;
204 \& my $cache = $args{HASH} || {};
205 \& bless $cache => $package;
206 \& }
207 \&
208 \& sub EXISTS {
209 \& my ($cache, $key) = @_;
210 \& if (exists $cache\->{$key} &&
211 \& $cache\->{$key}{EXPIRE_TIME} > time) {
212 \& return 1
213 \& } else {
214 \& return 0; # Do NOT return undef here
215 \& }
216 \& }
217 \&
218 \& sub FETCH {
219 \& my ($cache, $key) = @_;
220 \& return $cache\->{$key}{VALUE};
221 \& }
222 \&
223 \& sub STORE {
224 \& my ($cache, $key, $newvalue) = @_;
225 \& $cache\->{$key}{VALUE} = $newvalue;
226 \& $cache\->{$key}{EXPIRE_TIME} = time + 10;
227 \& }
228 .Ve
229 .PP
230 To use this expiration policy, the user would say
231 .PP
232 .Vb 3
233 \& use Memoize;
234 \& tie my %cache10sec => \*(AqMemoize::TenSecondExpire\*(Aq;
235 \& memoize \*(Aqfunction\*(Aq, SCALAR_CACHE => [HASH => \e%cache10sec];
236 .Ve
237 .PP
238 Memoize would then call \f(CW\*(C`function\*(C'\fR whenever a cached value was
239 entirely absent or was older than ten seconds.
240 .PP
241 You should always support a \f(CW\*(C`HASH\*(C'\fR argument to \f(CW\*(C`TIEHASH\*(C'\fR that ties
242 the underlying cache so that the user can specify that the cache is
243 also persistent or that it has some other interesting semantics. The
244 example above demonstrates how to do this, as does \f(CW\*(C`Memoize::Expire\*(C'\fR.
245 .PP
246 Another sample module, Memoize::Saves, is available in a separate
247 distribution on CPAN. It implements a policy that allows you to
248 specify that certain function values would always be looked up afresh.
249 See the documentation for details.
250 .SH ALTERNATIVES
251 .IX Header "ALTERNATIVES"
252 Brent Powers has a Memoize::ExpireLRU module that was designed to
253 work with Memoize and provides expiration of least-recently-used data.
254 The cache is held at a fixed number of entries, and when new data
255 comes in, the least-recently used data is expired.
256 .PP
257 Joshua Chamas's Tie::Cache module may be useful as an expiration
258 manager. (If you try this, let me know how it works out.)
259 .PP
260 If you develop any useful expiration managers that you think should be
261 distributed with Memoize, please let me know.
262 .SH CAVEATS
263 .IX Header "CAVEATS"
264 This module is experimental, and may contain bugs. Please report bugs
265 to the address below.
266 .PP
267 Number-of-uses is stored as a 16\-bit unsigned integer, so can't exceed
268 65535.
269 .PP
270 Because of clock granularity, expiration times may occur up to one
271 second sooner than you expect. For example, suppose you store a value
272 with a lifetime of ten seconds, and you store it at 12:00:00.998 on a
273 certain day. Memoize will look at the clock and see 12:00:00. Then
274 9.01 seconds later, at 12:00:10.008 you try to read it back. Memoize
275 will look at the clock and see 12:00:10 and conclude that the value
276 has expired. This will probably not occur if you have
277 \&\f(CW\*(C`Time::HiRes\*(C'\fR installed.
278 .SH AUTHOR
279 .IX Header "AUTHOR"
280 Mark-Jason Dominus
281 .PP
282 Mike Cariaso provided valuable insight into the best way to solve this
283 problem.
284 .SH "SEE ALSO"
285 .IX Header "SEE ALSO"
286 \&\fBperl\fR\|(1)
287 .PP
288 The Memoize man page.