Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Memoize::Expire.3pm

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