| 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 |
|