.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "CHI::Memoize 3pm"
.TH CHI::Memoize 3pm "2018-10-03" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CHI::Memoize \- Make functions faster with memoization, via CHI
.SH "VERSION"
.IX Header "VERSION"
version 0.07
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use CHI::Memoize qw(:all);
\&    
\&    # Straight memoization in memory
\&    memoize(\*(Aqfunc\*(Aq);
\&    memoize(\*(AqSome::Package::func\*(Aq);
\&
\&    # Memoize to a file or to memcached
\&    memoize( \*(Aqfunc\*(Aq, driver => \*(AqFile\*(Aq, root_dir => \*(Aq/path/to/cache\*(Aq );
\&    memoize( \*(Aqfunc\*(Aq, driver => \*(AqMemcached\*(Aq, servers => ["127.0.0.1:11211"] );
\&
\&    # Expire after one hour
\&    memoize(\*(Aqfunc\*(Aq, expires_in => \*(Aq1h\*(Aq);
\&    
\&    # Memoize based on the second and third argument to func
\&    memoize(\*(Aqfunc\*(Aq, key => sub { $_[1], $_[2] });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
"`Memoizing' a function makes it faster by trading space for time.  It does
this by caching the return values of the function in a table.  If you call the
function again with the same arguments, \f(CW\*(C`memoize\*(C'\fR jumps in and gives you the
value out of the table, instead of letting the function compute the value all
over again." \*(-- quoted from the original Memoize
.PP
For a bit of history and motivation, see
.PP
.Vb 1
\&    http://www.openswartz.com/2012/05/06/memoize\-revisiting\-a\-twelve\-year\-old\-api/
.Ve
.PP
\&\f(CW\*(C`CHI::Memoize\*(C'\fR provides the same facility as Memoize, but backed by
\&\s-1CHI\s0. This means, among other things, that you can
.IP "\(bu" 4
specify expiration times (expires_in) and conditions
(expire_if)
.IP "\(bu" 4
memoize to different backends, e.g. File,
Memcached, \s-1DBI\s0, or to
multilevel caches
.IP "\(bu" 4
handle arbitrarily complex function arguments (via \s-1CHI\s0 key
serialization)
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
All of these are importable; only \f(CW\*(C`memoize\*(C'\fR is imported by default. \f(CW\*(C`use
Memoize qw(:all)\*(C'\fR will import them all as well as the \f(CW\*(C`NO_MEMOIZE\*(C'\fR constant.
.ie n .IP "memoize ($func, %options)" 4
.el .IP "memoize ($func, \f(CW%options\fR)" 4
.IX Item "memoize ($func, %options)"
Creates a new function wrapped around \fI\f(CI$func\fI\fR that caches results based on
passed arguments.
.Sp
\&\fI\f(CI$func\fI\fR can be a function name (with or without a package prefix) or an
anonymous function. In the former case, the name is rebound to the new
function. In either case a code ref to the new wrapper function is returned.
.Sp
.Vb 3
\&    # Memoize a named function
\&    memoize(\*(Aqfunc\*(Aq);
\&    memoize(\*(AqSome::Package::func\*(Aq);
\&
\&    # Memoize an anonymous function
\&    $anon = memoize($anon);
.Ve
.Sp
By default, the cache key is formed from combining the full function name, the
calling context (\*(L"L\*(R" or \*(L"S\*(R"), and all the function arguments with canonical
\&\s-1JSON\s0 (sorted hash keys). e.g. these calls will be memoized together:
.Sp
.Vb 2
\&    memoized_function({a => 5, b => 6, c => { d => 7, e => 8 }});
\&    memoized_function({b => 6, c => { e => 8, d => 7 }, a => 5});
.Ve
.Sp
because the two hashes being passed are canonically the same. But these will be
memoized separately because of context:
.Sp
.Vb 2
\&     my $scalar = memoized_function(5);
\&     my @list = memoized_function(5);
.Ve
.Sp
By default, the cache namespace is formed from the full
function name or the stringified code reference.  This allows you to introspect
and clear the memoized results for a particular function.
.Sp
\&\f(CW\*(C`memoize\*(C'\fR throws an error if \fI\f(CI$func\fI\fR is already memoized.
.Sp
See \s-1OPTIONS\s0 below for what can go in the options hash.
.IP "memoized ($func)" 4
.IX Item "memoized ($func)"
Returns a CHI::Memoize::Info object if \fI\f(CI$func\fI\fR has been
memoized, or undef if it has not been memoized.
.Sp
.Vb 4
\&    # The CHI cache where memoize results are stored
\&    #
\&    my $cache = memoized($func)\->cache;
\&    $cache\->clear;
\&
\&    # Code references to the original function and to the new wrapped function
\&    #
\&    my $orig = memoized($func)\->orig;
\&    my $wrapped = memoized($func)\->wrapped;
.Ve
.IP "unmemoize ($func)" 4
.IX Item "unmemoize ($func)"
Removes the wrapper around \fI\f(CI$func\fI\fR, restoring it to its original unmemoized
state.  Also clears the memoize cache if possible (not supported by all
drivers, particularly memcached). Throws an error if
\&\fI\f(CI$func\fI\fR has not been memoized.
.Sp
.Vb 3
\&    memoize(\*(AqSome::Package::func\*(Aq);
\&    ...
\&    unmemoize(\*(AqSome::Package::func\*(Aq);
.Ve
.SS "\s-1OPTIONS\s0"
.IX Subsection "OPTIONS"
The following options can be passed to \*(L"memoize\*(R".
.IP "key" 4
.IX Item "key"
Specifies a code reference that takes arguments passed to the function and
returns a cache key. The key may be returned as a list, list reference or hash
reference; it will automatically be serialized to \s-1JSON\s0 in canonical mode
(sorted hash keys).
.Sp
For example, this uses the second and third argument to the function as a key:
.Sp
.Vb 1
\&    memoize(\*(Aqfunc\*(Aq, key => sub { @_[1..2] });
.Ve
.Sp
and this is useful for functions that accept a list of key/value pairs:
.Sp
.Vb 2
\&    # Ignore order of key/value pairs
\&    memoize(\*(Aqfunc\*(Aq, key => sub { %@_ });
.Ve
.Sp
Regardless of what key you specify, it will automatically be prefixed with the
full function name and the calling context (\*(L"L\*(R" or \*(L"S\*(R").
.Sp
If the coderef returns \f(CW\*(C`CHI::Memoize::NO_MEMOIZE\*(C'\fR (or \f(CW\*(C`NO_MEMOIZE\*(C'\fR if you
import it), this call won't be memoized. This is useful if you have a cache of
limited size or if you know certain arguments will yield nondeterministic
results. e.g.
.Sp
.Vb 1
\&    memoize(\*(Aqfunc\*(Aq, key => sub { $is_worth_caching ? @_ : NO_MEMOIZE });
.Ve
.IP "set and get options" 4
.IX Item "set and get options"
You can pass any of \s-1CHI\s0's set options (e.g.
expires_in, expires_variance) or
get options (e.g. expire_if,
busy_lock). e.g.
.Sp
.Vb 2
\&    # Expire after one hour
\&    memoize(\*(Aqfunc\*(Aq, expires_in => \*(Aq1h\*(Aq);
\&    
\&    # Expire when a particular condition occurs
\&    memoize(\*(Aqfunc\*(Aq, expire_if => sub { ... });
.Ve
.IP "cache options" 4
.IX Item "cache options"
Any remaining options will be passed to the \s-1CHI\s0 constructor
to generate the cache:
.Sp
.Vb 2
\&    # Store in file instead of memory
\&    memoize( \*(Aqfunc\*(Aq, driver => \*(AqFile\*(Aq, root_dir => \*(Aq/path/to/cache\*(Aq );
\&
\&    # Store in memcached instead of memory
\&    memoize(\*(Aqfunc\*(Aq, driver => \*(AqMemcached\*(Aq, servers => ["127.0.0.1:11211"]);
.Ve
.Sp
Unless specified, the namespace is generated from the full
name of the function being memoized.
.Sp
You can also specify an existing cache object:
.Sp
.Vb 3
\&    # Store in memcached instead of memory
\&    my $cache = CHI\->new(driver => \*(AqMemcached\*(Aq, servers => ["127.0.0.1:11211"]);
\&    memoize(\*(Aqfunc\*(Aq, cache => $cache);
.Ve
.SH "CLONED VS RAW REFERENCES"
.IX Header "CLONED VS RAW REFERENCES"
By default \f(CW\*(C`CHI\*(C'\fR, and thus \f(CW\*(C`CHI::Memoize\*(C'\fR, returns a deep clone of the stored
value \fIeven\fR when caching in memory. e.g. in this code
.PP
.Vb 4
\&    # func returns a list reference
\&    memoize(\*(Aqfunc\*(Aq);
\&    my $ref1 = func();
\&    my $ref2 = func();
.Ve
.PP
\&\f(CW$ref1\fR and \f(CW$ref2\fR will be references to two completely different lists
which have the same contained values. More specifically, the value is
serialized by Storable on \f(CW\*(C`set\*(C'\fR and deserialized
(hence cloned) on \f(CW\*(C`get\*(C'\fR.
.PP
The advantage here is that it is safe to modify a reference returned from a
memoized function; your modifications won't affect the cached value.
.PP
.Vb 4
\&    my $ref1 = func();
\&    push(@$ref1, 3, 4, 5);
\&    my $ref2 = func();
\&    # $ref2 does not have 3, 4, 5
.Ve
.PP
The disadvantage is that it takes extra time to serialize and deserialize the
value, and that some values like code references may be more difficult to
store. And cloning may not be what you want at all, e.g. if you are returning
objects.
.PP
Alternatively you can use CHI::Driver::RawMemory,
which will store raw references the way \f(CW\*(C`Memoize\*(C'\fR does. Now, however, any
modifications to the contents of a returned reference will affect the cached
value.
.PP
.Vb 6
\&    memoize(\*(Aqfunc\*(Aq, driver => \*(AqRawMemory\*(Aq);
\&    my $ref1 = func();
\&    push(@$ref1, 3, 4, 5);
\&    my $ref2 = func();
\&    # $ref1 eq $ref2
\&    # $ref2 has 3, 4, 5
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
The caveats of Memoize apply here as well.  To summarize:
.IP "\(bu" 4
Do not memoize a function whose behavior depends on program state other than
its own arguments, unless you explicitly capture that state in your computed
key.
.IP "\(bu" 4
Do not memoize a function with side effects, as the side effects won't happen
on a cache hit.
.IP "\(bu" 4
Do not memoize a very simple function, as the costs of caching will outweigh
the costs of the function itself.
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
.IP "\(bu" 4
Memoizing a function will affect its call stack and its prototype.
.SH "RELATED MODULES"
.IX Header "RELATED MODULES"
A number of modules address a subset of the problems addressed by this module,
including:
.IP "\(bu" 4
Memoize::Expire \- pluggable expiration of memoized values
.IP "\(bu" 4
Memoize::ExpireLRU \- provides \s-1LRU\s0 expiration for Memoize
.IP "\(bu" 4
Memoize::Memcached \- use a memcached cache to memoize functions
.SH "SUPPORT"
.IX Header "SUPPORT"
Questions and feedback are welcome, and should be directed to the perl-cache
mailing list:
.PP
.Vb 1
\&    http://groups.google.com/group/perl\-cache\-discuss
.Ve
.PP
Bugs and feature requests will be tracked at \s-1RT:\s0
.PP
.Vb 2
\&    http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI\-Memoize
\&    bug\-chi\-memoize@rt.cpan.org
.Ve
.PP
The latest source code can be browsed and fetched at:
.PP
.Vb 2
\&    http://github.com/jonswar/perl\-chi\-memoize
\&    git clone git://github.com/jonswar/perl\-chi\-memoize.git
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1CHI\s0, Memoize
.SH "AUTHOR"
.IX Header "AUTHOR"
Jonathan Swartz <swartz@pobox.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011 by Jonathan Swartz.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.