.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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 .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Cache::Ref 3pm" .TH Cache::Ref 3pm "2021-01-07" "perl v5.32.0" "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" Cache::Ref \- Memory only cache of live references .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # 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; \& \& \& # \*(Aqhit\*(Aq is like \*(Aqget\*(Aq without the overhead of obtaining the value \& # it\*(Aqs useful for keeping values from expiring when you already have \& # the values \& $cache\->hit("foo"); # also takes a list of keys .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Unlike \s-1CHI\s0 which attempts to address the problem of caching things persistently, this module implements in memory caching, designed primarily for \&\fBshared references\fR in memory. .PP This collection of classes implements a number of semi related algorithms. .SH "METHODS" .IX Header "METHODS" .ie n .IP "get @keys" 4 .el .IP "get \f(CW@keys\fR" 4 .IX Item "get @keys" Fetch entries from the cache. .ie n .IP "hit @keys" 4 .el .IP "hit \f(CW@keys\fR" 4 .IX Item "hit @keys" Promote \f(CW@keys\fR in the cache. .Sp Same effect as \f(CW\*(C`get\*(C'\fR except it doesn't actually return anything. .ie n .IP "set $key => $value" 4 .el .IP "set \f(CW$key\fR => \f(CW$value\fR" 4 .IX Item "set $key => $value" Adds an entry to the cache. .ie n .IP "compute $key, sub { ...; return $value }" 4 .el .IP "compute \f(CW$key\fR, sub { ...; return \f(CW$value\fR }" 4 .IX Item "compute $key, sub { ...; return $value }" Calls \f(CW\*(C`get\*(C'\fR with \f(CW$key\fR. 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 \f(CW\*(C`set\*(C'\fR. .ie n .IP "remove @keys" 4 .el .IP "remove \f(CW@keys\fR" 4 .IX Item "remove @keys" Remove specific entries from the cache. .ie n .IP "expire $x" 4 .el .IP "expire \f(CW$x\fR" 4 .IX Item "expire $x" Remove \f(CW$x\fR many entries from the cache. Hopefully the entries removed are the most useless ones. .Sp \&\f(CW$x\fR defaults to 1. .IP "clear" 4 .IX Item "clear" Empty the cache. .SH "ALGORITHMS" .IX Header "ALGORITHMS" .SS "\s-1FIFO\s0" .IX Subsection "FIFO" This is a simple \s-1FIFO\s0 queue where a \f(CW\*(C`set\*(C'\fR 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. .PP 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. .PP This implementation has the lowest memory overhead, due to the simplicity of its data structures (just a hash and an array). .PP 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. .PP For truly random access cache hit rates will suffer. .PP Long term utility of cache entries is not considered at all, so scans will poison the cache. .PP This is the only algorithm for which \f(CW\*(C`get\*(C'\fR (and \f(CW\*(C`hit\*(C'\fR) has no side effects. .SS "\s-1LRU\s0" .IX Subsection "LRU" This implementation uses an \s-1LRU\s0 list of entries (two implementations are provided for trading off memory for speed). .PP Long term utility of cache entries is not considered at all, so scans will poison the cache. .PP \fICache::Ref::Util::LRU::List\fR .IX Subsection "Cache::Ref::Util::LRU::List" .PP Uses a doubly linked list to perform \s-1MRU\s0 propagation. .PP Faster than Array. .PP Cache hits and \s-1LRU\s0 removal is O(1). .PP \fICache::Ref::Util::LRU::Array\fR .IX Subsection "Cache::Ref::Util::LRU::Array" .PP Generally slower for a cache size bigger than about 10 elements, but uses less memory due to the compact layout. .PP Cache hits are O(cache size). \s-1LRU\s0 removal is O(1). .SS "\s-1CLOCK\s0" .IX Subsection "CLOCK" This is an implementation of second chance \s-1FIFO,\s0 using a circular buffer. .PP Second chance \s-1FIFO\s0 is a very simple approximation of \s-1LRU.\s0 The \s-1CLOCK\s0 algorithm has its origins in Multics' virtual memory paging implementation. .PP It's slightly more general purpose than \s-1FIFO\s0 when dealing with random access. .PP Long term utility of cache entries is not considered at all, so scans will poison the cache. .PP Using values of \f(CW\*(C`k\*(C'\fR bigger than 1 (the default), more accurate approximations of \s-1LRU\s0 can be made, at the cost of more complicated expiry. .SS "\s-1GCLOCK\s0" .IX Subsection "GCLOCK" Tries to approximate \s-1LFU\s0 instead of \s-1LRU.\s0 .PP Cache hits increment a counter by one, instead of resetting it to the constant \f(CW\*(C`k\*(C'\fR. .PP Cache replacement decays existing counters just like \s-1CLOCK.\s0 .SS "\s-1CAR\s0" .IX Subsection "CAR" \&\s-1CLOCK\s0 with Adaptive Removal. .PP A self tuning cache that varies between approximations of \s-1LRU\s0 and \s-1LFU\s0 expiry. .PP Has the highest memory overhead of all the implementations due to the extent of the metadata it maintains. .PP However, this overhead is still small for when sizeable objects are involved. .PP Resistent to cache poisoning when scanning. .SS "\s-1CART\s0" .IX Subsection "CART" \&\s-1CAR\s0 with temporal filtering. .PP Like \s-1CAR\s0 but does not promote a cache entry to the long term usefulness set due to frequent successive access. .PP This is probably the most general purpose algorithm. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\s-1CHI\s0" 4 .IX Item "CHI" Appropriate for persistent caching of data with complex expiry. .IP "Cache::Cascade" 4 .IX Item "Cache::Cascade" Can be used to layer Cache::Ref over other caches (e.g. \s-1CHI\s0). .IP "Cache::Bounded" 4 .IX Item "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. .IP "Cache::Weak" 4 .IX Item "Cache::Weak" Caches shared references for as long as there is some other reference to those objects. .IP "Cache::Profile" 4 .IX Item "Cache::Profile" Designed to help choose an appropriate cache layer. .IP "Algorithm information" 4 .IX Item "Algorithm information" .Sp .Sp .SH "VERSION CONTROL" .IX Header "VERSION CONTROL" .SH "AUTHOR" .IX Header "AUTHOR" Yuval Kogman .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2010 by Yuval Kogman. .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.