.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 "Tie::Cache::LRU::Virtual 3pm"
.TH Tie::Cache::LRU::Virtual 3pm "2022-08-29" "perl v5.34.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"
Tie::Cache::LRU::Virtual \- Virtual base class for Tie::Cache::LRU::*
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package My::Tie::Cache::LRU;
\&
\&  use base qw(Tie::Cache::LRU::Virtual);
\&
\&  ...override and define key methods...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a pure virtual base class defining the public methods of
Tie::Cache::LRU.  It is intended that you will subclass off of it and
fill in the missing/incomplete methods.
.PP
You must implement the entire hash interface.
.PP
.Vb 8
\&    TIEHASH
\&    CLEAR
\&    FETCH
\&    STORE
\&    EXISTS
\&    DELETE
\&    FIRSTKEY
\&    NEXTKEY
.Ve
.PP
And the object interface
.PP
.Vb 2
\&    curr_size
\&    max_size
.Ve
.PP
As well as \s-1DESTROY\s0 if necessary.
.PP
I'm usually not taken to such heights of \s-1OO\s0 formality, but in this
case a virtual class seemed in order.
.SH "USAGE"
.IX Header "USAGE"
The cache is extremely simple, is just holds a simple scalar.  If you
want to cache an object, just place it into the cache:
.PP
.Vb 1
\&    $cache{$obj\->id} = $obj;
.Ve
.PP
This doesn't make a copy of the object, it just holds a reference to
it.  (Note: This means that your object's destructor will not be
called until it has fallen out of the cache (and all other references
to it have disappeared, of course)!)
.PP
If you want to cache an array, place a reference to it in the cache:
.PP
.Vb 1
\&    $cache{$some_id} = \e@array;
.Ve
.PP
Or, if you're worried about the consequences of tossing around
references and want to cache a copy instead, you can do something like
this:
.PP
.Vb 1
\&    $cache{$some_id} = [@array];
.Ve
.SS "Tied Interface"
.IX Subsection "Tied Interface"
.IP "\fBtie\fR" 4
.IX Item "tie"
.Vb 2
\&    tie %cache, \*(AqTie::Cache::LRU\*(Aq;
\&    tie %cache, \*(AqTie::Cache::LRU\*(Aq, $cache_size;
.Ve
.Sp
This ties a cache to \f(CW%cache\fR which will hold a maximum of \f(CW$cache_size\fR
keys.  If \f(CW$cache_size\fR is not given it uses a default value,
Tie::Cache::LRU::DEFAULT_MAX_SIZE.
.Sp
If the size is set to 0, the cache is effectively turned off.  This is
useful for \*(L"removing\*(R" the cache from a program without having to make
deep alterations to the program itself, or for checking performance
differences with and without a cache.
.Sp
All of the expected hash operations (exists, delete, slices, etc...) 
work on the \f(CW%cache\fR.
.SS "Object Interface"
.IX Subsection "Object Interface"
There's a few things you just can't do through the tied interface.  To
do them, you need to get at the underlying object, which you do with
\&\fBtied()\fR.
.PP
.Vb 1
\&    $cache_obj = tied %cache;
.Ve
.PP
And then you can call a few methods on that object:
.IP "\fBmax_size\fR" 4
.IX Item "max_size"
.Vb 2
\&  $cache_obj\->max_size($size);
\&  $size = $cache_obj\->max_size;
.Ve
.Sp
An accessor to alter the maximum size of the cache on the fly.
.Sp
If \fBmax_size()\fR is reset, and it is lower than the current size, the cache
is immediately truncated.
.Sp
The size must be an integer greater than or equal to 0.
.IP "\fBcurr_size\fR" 4
.IX Item "curr_size"
.Vb 1
\&  $size = $cache_obj\->curr_size;
.Ve
.Sp
Returns the current number of items in the cache.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael G Schwern <schwern@pobox.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Tie::Cache::LRU, Tie::Cache::LRU::LinkedList,
Tie::Cache::LRU::Array, Tie::Cache