view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        `memoize' throws an error if *$func* is already memoized.

        See OPTIONS below for what can go in the options hash.

    memoized ($func)
        Returns a CHI::Memoize::Info object if *$func* has been memoized, or
        undef if it has not been memoized.

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

    unmemoize ($func)
        Removes the wrapper around *$func*, 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 *$func* has not been memoized.

            memoize('Some::Package::func');
            ...
            unmemoize('Some::Package::func');

  OPTIONS
    The following options can be passed to memoize.

    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 JSON in canonical mode (sorted hash keys).

        For example, this uses the second and third argument to the function
        as a key:

            memoize('func', key => sub { @_[1..2] });

        and this is useful for functions that accept a list of key/value
        pairs:

            # Ignore order of key/value pairs
            memoize('func', key => sub { %@_ });

        Regardless of what key you specify, it will automatically be
        prefixed with the full function name and the calling context ("L" or
        "S").

        If the coderef returns `CHI::Memoize::NO_MEMOIZE' (or `NO_MEMOIZE'
        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.

            memoize('func', key => sub { $is_worth_caching ? @_ : NO_MEMOIZE });

    set and get options
        You can pass any of CHI's set options (e.g. expires_in,
        expires_variance) or get options (e.g. expire_if, busy_lock). e.g.

            # Expire after one hour
            memoize('func', expires_in => '1h');
    
            # Expire when a particular condition occurs
            memoize('func', expire_if => sub { ... });

    cache options
        Any remaining options will be passed to the CHI constructor to
        generate the cache:

            # Store in file instead of memory
            memoize( 'func', driver => 'File', root_dir => '/path/to/cache' );

            # Store in memcached instead of memory
            memoize('func', driver => 'Memcached', servers => ["127.0.0.1:11211"]);

        Unless specified, the namespace is generated from the full name of
        the function being memoized.

        You can also specify an existing cache object:

            # Store in memcached instead of memory
            my $cache = CHI->new(driver => 'Memcached', servers => ["127.0.0.1:11211"]);
            memoize('func', cache => $cache);

CLONED VS RAW REFERENCES
    By default `CHI', and thus `CHI::Memoize', returns a deep clone of the
    stored value *even* when caching in memory. e.g. in this code

        # func returns a list reference
        memoize('func');
        my $ref1 = func();
        my $ref2 = func();

    `$ref1' and `$ref2' will be references to two completely different lists
    which have the same contained values. More specifically, the value is
    serialized by Storable on `set' and deserialized (hence cloned) on
    `get'.

    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.

        my $ref1 = func();
        push(@$ref1, 3, 4, 5);
        my $ref2 = func();
        # $ref2 does not have 3, 4, 5

    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.

    Alternatively you can use CHI::Driver::RawMemory, which will store raw
    references the way `Memoize' does. Now, however, any modifications to
    the contents of a returned reference will affect the cached value.

        memoize('func', driver => 'RawMemory');
        my $ref1 = func();