view release on metacpan or  search on metacpan

lib/CHI.pm  view on Meta::CPAN

    d day days
    w week weeks
    M month months
    y year years

e.g. the following are all valid duration expressions:

    25
    3s
    5 seconds
    1 minute and ten seconds
    1 hour

=head1 KEY AND VALUE TRANSFORMATIONS

CHI strives to accept arbitrary keys and values for caching regardless of the
limitations of the underlying driver.

=head2 Key transformations

=over

=item *

Keys that are references are serialized - see L</key_serializer>.

=item *

Keys with wide (>255) characters are utf8 encoded.

=item *

Keys exceeding the maximum length for the underlying driver are digested - see
L</max_key_length> and L</key_digester>.

=item *

For some drivers (e.g. L<CHI::Driver::File|File>), keys containing special
characters or whitespace are escaped with URL-like escaping.

=back

Note: All transformations above with the exception of escaping are I<one-way>,
meaning that CHI does not attempt to undo them when returned from L</get_keys>;
and I<idempotent>, meaning that applying them a second time has no effect. So
when you call L</get_keys>, the key you get may not be exactly what you passed
in, but you'll be able to pass that key in to get the corresponding object.

=head2 Value transformations

=over

=item *

Values which are references are automatically serialized before storing, and
deserialized after retrieving - see L</serializer>.

=item *

Values with their utf8 flag on are utf8 encoded before storing, and utf8
decoded after retrieving.

=back

=head1 SUBCACHES

It is possible to a cache to have one or more I<subcaches>. There are currently
two types of subcaches: I<L1> and I<mirror>.

=head2 L1 cache

An L1 (or "level one") cache sits in front of the primary cache, usually to
provide faster access for commonly accessed cache entries. For example, this
places an in-process Memory cache in front of a Memcached cache:

    my $cache = CHI->new(
        driver   => 'Memcached',
        servers  => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
        l1_cache => { driver => 'Memory', global => 1, max_size => 1024*1024 }
    );

On a C<get>, the L1 cache is checked first - if a valid value exists, it is
returned. Otherwise, the primary cache is checked - if a valid value exists, it
is returned, and the value is placed in the L1 cache with the same expiration
time. In this way, items fetched most frequently from the primary cache will
tend to be in the L1 cache.

C<set> operations are distributed to both the primary and L1 cache.

You can access the L1 cache with the C<l1_cache> method. For example, this
clears the L1 cache but leaves the primary cache intact:

    $cache->l1_cache->clear();

=head2 Mirror cache

A mirror cache is a write-only cache that, over time, mirrors the content of
the primary cache. C<set> operations are distributed to both the primary and
mirror cache, but C<get> operations go only to the primary cache.

Mirror caches are useful when you want to migrate from one cache to another.
You can populate a mirror cache and switch over to it once it is sufficiently
populated. For example, here we migrate from an old to a new cache directory:

    my $cache = CHI->new(
        driver          => 'File',
        root_dir        => '/old/cache/root',
        mirror_cache => { driver => 'File', root_dir => '/new/cache/root' },
    );

We leave this running for a few hours (or as needed), then replace it with

    my $cache = CHI->new(
        driver   => 'File',
        root_dir => '/new/cache/root'
    );

You can access the mirror cache with the C<mirror_cache> method. For example,
to see how many keys have made it over to the mirror cache:

    my @keys = $cache->mirror_cache->get_keys();