File Coverage

blib/lib/Tie/Cache/LRU/Virtual.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1             package Tie::Cache::LRU::Virtual;
2              
3 5     5   1130 use strict;
  5         11  
  5         338  
4              
5 5     5   28 use base qw(Class::Virtual Class::Data::Inheritable);
  5         12  
  5         7323  
6              
7             __PACKAGE__->mk_classdata('DEFAULT_MAX_SIZE');
8             __PACKAGE__->DEFAULT_MAX_SIZE(500);
9              
10             __PACKAGE__->virtual_methods(qw(TIEHASH
11             CLEAR
12             FETCH
13             STORE
14             EXISTS
15             DELETE
16             FIRSTKEY
17             NEXTKEY
18             DESTROY
19              
20             curr_size
21             max_size
22             )
23             );
24              
25             =pod
26              
27             =head1 NAME
28              
29             Tie::Cache::LRU::Virtual - Virtual base class for Tie::Cache::LRU::*
30              
31             =head1 SYNOPSIS
32              
33             package My::Tie::Cache::LRU;
34              
35             use base qw(Tie::Cache::LRU::Virtual);
36              
37             ...override and define key methods...
38              
39             =head1 DESCRIPTION
40              
41             This is a pure virtual base class defining the public methods of
42             Tie::Cache::LRU. It is intended that you will subclass off of it and
43             fill in the missing/incomplete methods.
44              
45             You must implement the entire hash interface.
46              
47             TIEHASH
48             CLEAR
49             FETCH
50             STORE
51             EXISTS
52             DELETE
53             FIRSTKEY
54             NEXTKEY
55              
56             And the object interface
57              
58             curr_size
59             max_size
60              
61             As well as DESTROY if necessary.
62              
63             I'm usually not taken to such heights of OO formality, but in this
64             case a virtual class seemed in order.
65              
66              
67             =head1 USAGE
68              
69             The cache is extremely simple, is just holds a simple scalar. If you
70             want to cache an object, just place it into the cache:
71              
72             $cache{$obj->id} = $obj;
73              
74             This doesn't make a copy of the object, it just holds a reference to
75             it. (Note: This means that your object's destructor will not be
76             called until it has fallen out of the cache (and all other references
77             to it have disappeared, of course)!)
78              
79             If you want to cache an array, place a reference to it in the cache:
80              
81             $cache{$some_id} = \@array;
82              
83             Or, if you're worried about the consequences of tossing around
84             references and want to cache a copy instead, you can do something like
85             this:
86              
87             $cache{$some_id} = [@array];
88              
89              
90             =head2 Tied Interface
91              
92             =over 4
93              
94             =item B
95              
96             tie %cache, 'Tie::Cache::LRU';
97             tie %cache, 'Tie::Cache::LRU', $cache_size;
98              
99             This ties a cache to %cache which will hold a maximum of $cache_size
100             keys. If $cache_size is not given it uses a default value,
101             Tie::Cache::LRU::DEFAULT_MAX_SIZE.
102              
103             If the size is set to 0, the cache is effectively turned off. This is
104             useful for "removing" the cache from a program without having to make
105             deep alterations to the program itself, or for checking performance
106             differences with and without a cache.
107              
108             All of the expected hash operations (exists, delete, slices, etc...)
109             work on the %cache.
110              
111              
112             =pod
113              
114             =back
115              
116             =head2 Object Interface
117              
118             There's a few things you just can't do through the tied interface. To
119             do them, you need to get at the underlying object, which you do with
120             tied().
121              
122             $cache_obj = tied %cache;
123              
124             And then you can call a few methods on that object:
125              
126             =over 4
127              
128             =item B
129              
130             $cache_obj->max_size($size);
131             $size = $cache_obj->max_size;
132              
133             An accessor to alter the maximum size of the cache on the fly.
134              
135             If max_size() is reset, and it is lower than the current size, the cache
136             is immediately truncated.
137              
138             The size must be an integer greater than or equal to 0.
139              
140              
141             =item B
142              
143             $size = $cache_obj->curr_size;
144              
145             Returns the current number of items in the cache.
146              
147             =back
148              
149              
150             =head1 AUTHOR
151              
152             Michael G Schwern
153              
154             =head1 SEE ALSO
155              
156             L, L,
157             L, L
158              
159             =cut
160              
161             1;
162