package Tie::Cache::LRU::Virtual;
use strict;
use base qw(Class::Virtual Class::Data::Inheritable);
__PACKAGE__->mk_classdata('DEFAULT_MAX_SIZE');
__PACKAGE__->DEFAULT_MAX_SIZE(500);
__PACKAGE__->virtual_methods(qw(TIEHASH
CLEAR
FETCH
STORE
EXISTS
DELETE
FIRSTKEY
NEXTKEY
DESTROY
curr_size
max_size
)
);
=pod
=head1 NAME
Tie::Cache::LRU::Virtual - Virtual base class for Tie::Cache::LRU::*
=head1 SYNOPSIS
package My::Tie::Cache::LRU;
use base qw(Tie::Cache::LRU::Virtual);
...override and define key methods...
=head1 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.
You must implement the entire hash interface.
TIEHASH
CLEAR
FETCH
STORE
EXISTS
DELETE
FIRSTKEY
NEXTKEY
And the object interface
curr_size
max_size
As well as DESTROY if necessary.
I'm usually not taken to such heights of OO formality, but in this
case a virtual class seemed in order.
=head1 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:
$cache{$obj->id} = $obj;
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)!)
If you want to cache an array, place a reference to it in the cache:
$cache{$some_id} = \@array;
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:
$cache{$some_id} = [@array];
=head2 Tied Interface
=over 4
=item B<tie>
tie %cache, 'Tie::Cache::LRU';
tie %cache, 'Tie::Cache::LRU', $cache_size;
This ties a cache to %cache which will hold a maximum of $cache_size
keys. If $cache_size is not given it uses a default value,
Tie::Cache::LRU::DEFAULT_MAX_SIZE.
If the size is set to 0, the cache is effectively turned off. This is
useful for "removing" 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.
All of the expected hash operations (exists, delete, slices, etc...)
work on the %cache.
=pod
=back
=head2 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
tied().
$cache_obj = tied %cache;
And then you can call a few methods on that object:
=over 4
=item B<max_size>
$cache_obj->max_size($size);
$size = $cache_obj->max_size;
An accessor to alter the maximum size of the cache on the fly.
If max_size() is reset, and it is lower than the current size, the cache
is immediately truncated.
The size must be an integer greater than or equal to 0.
=item B<curr_size>
$size = $cache_obj->curr_size;
Returns the current number of items in the cache.
=back
=head1 AUTHOR
Michael G Schwern <schwern@pobox.com>
=head1 SEE ALSO
L<Tie::Cache::LRU>, L<Tie::Cache::LRU::LinkedList>,
L<Tie::Cache::LRU::Array>, L<Tie::Cache>
=cut
1;