Debian Codegraph @

README

raw
1 NAME
2 CHI::Memoize - Make functions faster with memoization, via CHI
3
4 VERSION
5 version 0.07
6
7 SYNOPSIS
8 use CHI::Memoize qw(:all);
9
10 # Straight memoization in memory
11 memoize('func');
12 memoize('Some::Package::func');
13
14 # Memoize to a file or to memcached
15 memoize( 'func', driver => 'File', root_dir => '/path/to/cache' );
16 memoize( 'func', driver => 'Memcached', servers => ["127.0.0.1:11211"] );
17
18 # Expire after one hour
19 memoize('func', expires_in => '1h');
20
21 # Memoize based on the second and third argument to func
22 memoize('func', key => sub { $_[1], $_[2] });
23
24 DESCRIPTION
25 "`Memoizing' a function makes it faster by trading space for time. It
26 does this by caching the return values of the function in a table. If
27 you call the function again with the same arguments, `memoize' jumps in
28 and gives you the value out of the table, instead of letting the
29 function compute the value all over again." -- quoted from the original
30 Memoize
31
32 For a bit of history and motivation, see
33
34 http://www.openswartz.com/2012/05/06/memoize-revisiting-a-twelve-year-old-api/
35
36 `CHI::Memoize' provides the same facility as Memoize, but backed by CHI.
37 This means, among other things, that you can
38
39 * specify expiration times (expires_in) and conditions (expire_if)
40
41 * memoize to different backends, e.g. File, Memcached, DBI, or to
42 multilevel caches
43
44 * handle arbitrarily complex function arguments (via CHI key
45 serialization)
46
47 FUNCTIONS
48 All of these are importable; only `memoize' is imported by default. `use
49 Memoize qw(:all)' will import them all as well as the `NO_MEMOIZE'
50 constant.
51
52 memoize ($func, %options)
53 Creates a new function wrapped around *$func* that caches results
54 based on passed arguments.
55
56 *$func* can be a function name (with or without a package prefix) or
57 an anonymous function. In the former case, the name is rebound to
58 the new function. In either case a code ref to the new wrapper
59 function is returned.
60
61 # Memoize a named function
62 memoize('func');
63 memoize('Some::Package::func');
64
65 # Memoize an anonymous function
66 $anon = memoize($anon);
67
68 By default, the cache key is formed from combining the full function
69 name, the calling context ("L" or "S"), and all the function
70 arguments with canonical JSON (sorted hash keys). e.g. these calls
71 will be memoized together:
72
73 memoized_function({a => 5, b => 6, c => { d => 7, e => 8 }});
74 memoized_function({b => 6, c => { e => 8, d => 7 }, a => 5});
75
76 because the two hashes being passed are canonically the same. But
77 these will be memoized separately because of context:
78
79 my $scalar = memoized_function(5);
80 my @list = memoized_function(5);
81
82 By default, the cache namespace is formed from the full function
83 name or the stringified code reference. This allows you to
84 introspect and clear the memoized results for a particular function.
85
86 `memoize' throws an error if *$func* is already memoized.
87
88 See OPTIONS below for what can go in the options hash.
89
90 memoized ($func)
91 Returns a CHI::Memoize::Info object if *$func* has been memoized, or
92 undef if it has not been memoized.
93
94 # The CHI cache where memoize results are stored
95 #
96 my $cache = memoized($func)->cache;
97 $cache->clear;
98
99 # Code references to the original function and to the new wrapped function
100 #
101 my $orig = memoized($func)->orig;
102 my $wrapped = memoized($func)->wrapped;
103
104 unmemoize ($func)
105 Removes the wrapper around *$func*, restoring it to its original
106 unmemoized state. Also clears the memoize cache if possible (not
107 supported by all drivers, particularly memcached). Throws an error
108 if *$func* has not been memoized.
109
110 memoize('Some::Package::func');
111 ...
112 unmemoize('Some::Package::func');
113
114 OPTIONS
115 The following options can be passed to memoize.
116
117 key Specifies a code reference that takes arguments passed to the
118 function and returns a cache key. The key may be returned as a list,
119 list reference or hash reference; it will automatically be
120 serialized to JSON in canonical mode (sorted hash keys).
121
122 For example, this uses the second and third argument to the function
123 as a key:
124
125 memoize('func', key => sub { @_[1..2] });
126
127 and this is useful for functions that accept a list of key/value
128 pairs:
129
130 # Ignore order of key/value pairs
131 memoize('func', key => sub { %@_ });
132
133 Regardless of what key you specify, it will automatically be
134 prefixed with the full function name and the calling context ("L" or
135 "S").
136
137 If the coderef returns `CHI::Memoize::NO_MEMOIZE' (or `NO_MEMOIZE'
138 if you import it), this call won't be memoized. This is useful if
139 you have a cache of limited size or if you know certain arguments
140 will yield nondeterministic results. e.g.
141
142 memoize('func', key => sub { $is_worth_caching ? @_ : NO_MEMOIZE });
143
144 set and get options
145 You can pass any of CHI's set options (e.g. expires_in,
146 expires_variance) or get options (e.g. expire_if, busy_lock). e.g.
147
148 # Expire after one hour
149 memoize('func', expires_in => '1h');
150
151 # Expire when a particular condition occurs
152 memoize('func', expire_if => sub { ... });
153
154 cache options
155 Any remaining options will be passed to the CHI constructor to
156 generate the cache:
157
158 # Store in file instead of memory
159 memoize( 'func', driver => 'File', root_dir => '/path/to/cache' );
160
161 # Store in memcached instead of memory
162 memoize('func', driver => 'Memcached', servers => ["127.0.0.1:11211"]);
163
164 Unless specified, the namespace is generated from the full name of
165 the function being memoized.
166
167 You can also specify an existing cache object:
168
169 # Store in memcached instead of memory
170 my $cache = CHI->new(driver => 'Memcached', servers => ["127.0.0.1:11211"]);
171 memoize('func', cache => $cache);
172
173 CLONED VS RAW REFERENCES
174 By default `CHI', and thus `CHI::Memoize', returns a deep clone of the
175 stored value *even* when caching in memory. e.g. in this code
176
177 # func returns a list reference
178 memoize('func');
179 my $ref1 = func();
180 my $ref2 = func();
181
182 `$ref1' and `$ref2' will be references to two completely different lists
183 which have the same contained values. More specifically, the value is
184 serialized by Storable on `set' and deserialized (hence cloned) on
185 `get'.
186
187 The advantage here is that it is safe to modify a reference returned
188 from a memoized function; your modifications won't affect the cached
189 value.
190
191 my $ref1 = func();
192 push(@$ref1, 3, 4, 5);
193 my $ref2 = func();
194 # $ref2 does not have 3, 4, 5
195
196 The disadvantage is that it takes extra time to serialize and
197 deserialize the value, and that some values like code references may be
198 more difficult to store. And cloning may not be what you want at all,
199 e.g. if you are returning objects.
200
201 Alternatively you can use CHI::Driver::RawMemory, which will store raw
202 references the way `Memoize' does. Now, however, any modifications to
203 the contents of a returned reference will affect the cached value.
204
205 memoize('func', driver => 'RawMemory');
206 my $ref1 = func();
207 push(@$ref1, 3, 4, 5);
208 my $ref2 = func();
209 # $ref1 eq $ref2
210 # $ref2 has 3, 4, 5
211
212 CAVEATS
213 The caveats of Memoize apply here as well. To summarize:
214
215 * Do not memoize a function whose behavior depends on program state
216 other than its own arguments, unless you explicitly capture that
217 state in your computed key.
218
219 * Do not memoize a function with side effects, as the side effects
220 won't happen on a cache hit.
221
222 * Do not memoize a very simple function, as the costs of caching will
223 outweigh the costs of the function itself.
224
225 KNOWN BUGS
226 * Memoizing a function will affect its call stack and its prototype.
227
228 RELATED MODULES
229 A number of modules address a subset of the problems addressed by this
230 module, including:
231
232 * Memoize::Expire - pluggable expiration of memoized values
233
234 * Memoize::ExpireLRU - provides LRU expiration for Memoize
235
236 * Memoize::Memcached - use a memcached cache to memoize functions
237
238 SUPPORT
239 Questions and feedback are welcome, and should be directed to the
240 perl-cache mailing list:
241
242 http://groups.google.com/group/perl-cache-discuss
243
244 Bugs and feature requests will be tracked at RT:
245
246 http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI-Memoize
247 [email protected]
248
249 The latest source code can be browsed and fetched at:
250
251 http://github.com/jonswar/perl-chi-memoize
252 git clone git://github.com/jonswar/perl-chi-memoize.git
253
254 SEE ALSO
255 CHI, Memoize
256
257 AUTHOR
258 Jonathan Swartz <[email protected]>
259
260 COPYRIGHT AND LICENSE
261 This software is copyright (c) 2011 by Jonathan Swartz.
262
263 This is free software; you can redistribute it and/or modify it under
264 the same terms as the Perl 5 programming language system itself.
265