NAME

       Cache::Ref - Memory only cache of live references

SYNOPSIS

           # this class is just a base class and a documentation start point
           # just use the various algorithms directly

           use Cache::Ref::CART;
           my $cache = Cache::Ref::CART->new( size => 1024 );

           # add a cache value or set an existing key to a new value
           $cache->set(foo => $some_object);

           # get a value
           $cache->get("foo"); # also takes a list of keys

           # remove a key before it has normally expired
           $cache->remove("foo");

           # remove all cached data
           $cache->clear;

           # 'hit' is like 'get' without the overhead of obtaining the value
           # it's useful for keeping values from expiring when you already have
           # the values
           $cache->hit("foo"); # also takes a list of keys

DESCRIPTION

       Unlike CHI which attempts to address the problem of caching things persistently, this
       module implements in memory caching, designed primarily for shared references in memory.

       This collection of classes implements a number of semi related algorithms.

METHODS

       get @keys
           Fetch entries from the cache.

       hit @keys
           Promote @keys in the cache.

           Same effect as "get" except it doesn't actually return anything.

       set $key => $value
           Adds an entry to the cache.

       compute $key, sub { ...; return $value }
           Calls "get" with $key. If there's a hit the value is returned. Otherwise the code
           block is executed to compute the value, and the result is stored in the cache using
           "set".

       remove @keys
           Remove specific entries from the cache.

       expire $x
           Remove $x many entries from the cache. Hopefully the entries removed are the most
           useless ones.

           $x defaults to 1.

       clear
           Empty the cache.

ALGORITHMS

   FIFO
       This is a simple FIFO queue where a "set" places the element on the head of a queue, and
       if the size is too big an element will be discarded from the tail of the queue.

       Cache::Bounded provides similar behavior, but flushing happens periodically and in bigger
       numbers. Therefore, performance will be better on very high cache usage, when hits don't
       matter that much.

       This implementation has the lowest memory overhead, due to the simplicity of its data
       structures (just a hash and an array).

       Its expiry policy is appropriate for when the data set has a high locality of reference,
       and random access is generally confined to neighbors, as a part of some larger scan.

       For truly random access cache hit rates will suffer.

       Long term utility of cache entries is not considered at all, so scans will poison the
       cache.

       This is the only algorithm for which "get" (and "hit") has no side effects.

   LRU
       This implementation uses an LRU list of entries (two implementations are provided for
       trading off memory for speed).

       Long term utility of cache entries is not considered at all, so scans will poison the
       cache.

       Cache::Ref::Util::LRU::List

       Uses a doubly linked list to perform MRU propagation.

       Faster than Array.

       Cache hits and LRU removal is O(1).

       Cache::Ref::Util::LRU::Array

       Generally slower for a cache size bigger than about 10 elements, but uses less memory due
       to the compact layout.

       Cache hits are O(cache size). LRU removal is O(1).

   CLOCK
       This is an implementation of second chance FIFO, using a circular buffer.

       Second chance FIFO is a very simple approximation of LRU. The CLOCK algorithm has its
       origins in Multics' virtual memory paging implementation.

       It's slightly more general purpose than FIFO when dealing with random access.

       Long term utility of cache entries is not considered at all, so scans will poison the
       cache.

       Using values of "k" bigger than 1 (the default), more accurate approximations of LRU can
       be made, at the cost of more complicated expiry.

   GCLOCK
       Tries to approximate LFU instead of LRU.

       Cache hits increment a counter by one, instead of resetting it to the constant "k".

       Cache replacement decays existing counters just like CLOCK.

   CAR
       CLOCK with Adaptive Removal.

       A self tuning cache that varies between approximations of LRU and LFU expiry.

       Has the highest memory overhead of all the implementations due to the extent of the
       metadata it maintains.

       However, this overhead is still small for when sizeable objects are involved.

       Resistent to cache poisoning when scanning.

   CART
       CAR with temporal filtering.

       Like CAR but does not promote a cache entry to the long term usefulness set due to
       frequent successive access.

       This is probably the most general purpose algorithm.

SEE ALSO

       CHI Appropriate for persistent caching of data with complex expiry.

       Cache::Cascade
           Can be used to layer Cache::Ref over other caches (e.g. CHI).

       Cache::Bounded
           A simpler implementation with similar goals (memory only caching), designed for when
           cache misses are not very high cost, so cache hits have an extremely low overhead and
           the policy is very simplistic.

       Cache::Weak
           Caches shared references for as long as there is some other reference to those
           objects.

       Cache::Profile
           Designed to help choose an appropriate cache layer.

       Algorithm information
           <http://en.wikipedia.org/wiki/Cache_algorithms>

           <http://en.wikipedia.org/wiki/Page_replacement_algorithm>

           <http://www.almaden.ibm.com/cs/people/dmodha/clockfast.pdf>

VERSION CONTROL

       <http://github.com/nothingmuch/Cache-Ref>

AUTHOR

       Yuval Kogman

COPYRIGHT AND LICENSE

       This software is copyright (c) 2010 by Yuval Kogman.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.