view release on metacpan or  search on metacpan

lib/CHI.pm  view on Meta::CPAN

    dump_as_hash

=head2 Multiple subcaches

It is valid for a cache to have one of each kind of subcache, e.g. an L1 cache
and a mirror cache.

A cache cannot have more than one of each kind of subcache, but a subcache can
have its own subcaches, and so on. e.g.

    my $cache = CHI->new(
        driver   => 'Memcached',
        servers  => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
        l1_cache => {
            driver     => 'File',
            root_dir   => '/path/to/root',
            l1_cache   => { driver => 'RawMemory', global => 1 }
        }
    );

=head2 Methods for parent caches

=over

=item has_subcaches( )

Returns a boolean indicating whether this cache has subcaches.

=item l1_cache( )

Returns the L1 cache for this cache, if any. Can only be called if
I<has_subcaches> is true.

=item mirror_cache( )

Returns the mirror cache for this cache, if any. Can only be called if
I<has_subcaches> is true.

=item subcaches( )

Returns the subcaches for this cache, in arbitrary order. Can only be called if
I<has_subcaches> is true.

=back

=head2 Methods for subcaches

=over

=item is_subcache( )

Returns a boolean indicating whether this is a subcache.

=item subcache_type( )

Returns the type of subcache as a string, e.g. 'l1_cache' or 'mirror_cache'.
Can only be called if I<is_subcache> is true.

=item parent_cache( )

Returns the parent cache (weakened to prevent circular reference).  Can only be
called if I<is_subcache> is true.

=back

=head2 Developing new kinds of subcaches

At this time, subcache behavior is hardcoded into CHI::Driver, so there is no
easy way to modify the behavior of existing subcache types or create new ones.
We'd like to make this more flexible eventually.

=head1 SIZE AWARENESS

If L</is_size_aware> or L</max_size> are passed to the constructor, the cache
will be I<size aware> - that is, it will keep track of its own size (in bytes)
as items are added and removed. You can get a cache's size with L</get_size>.

Size aware caches generally keep track of their size in a separate meta-key,
and have to do an extra store whenever the size changes (e.g. on each set and
remove).

=head2 Maximum size and discard policies

If a cache's size rises above its L</max_size>, items are discarded until the
cache size is sufficiently below the max size. (See
L</max_size_reduction_factor> for how to fine-tune this.)

The order in which items are discarded is controlled with L</discard_policy>.
The default discard policy is 'arbitrary', which discards items in an arbitrary
order.  The available policies and default policy can differ with each driver,
e.g. the L<CHI::Driver::Memory|Memory> driver provides and defaults to an 'LRU'
policy.

=head2 Appropriate drivers

Size awareness was chiefly designed for, and works well with, the
L<CHI::Driver::Memory|Memory> driver: one often needs to enforce a maximum size
on a memory cache, and the overhead of tracking size in memory is negligible.
However, the capability may be useful with other drivers.

Some drivers - for example, L<CHI::Driver::FastMmap|FastMmap> and
L<CHI::Driver::Memcached|Memcached> - inherently keep track of their size and
enforce a maximum size, and it makes no sense to turn on CHI's size awareness
for these.

Also, for drivers that cannot atomically read and update a value - for example,
L<CHI::Driver::File|File> - there is a race condition in the updating of size
that can cause the size to grow inaccurate over time.

=head1 SUBCLASSING AND CONFIGURING CHI

You can subclass CHI for your own application and configure it in a variety of
ways, e.g. predefining storage types and defaults for new cache objects. Your
configuration will be independent of the main CHI class and other CHI
subclasses.

Start with a trivial subclass:

    package My::CHI;

    use base qw(CHI);