Debian Codegraph @

README

raw
1 NAME
2 Tie::Cache - LRU Cache in Memory
3
4 SYNOPSIS
5 use Tie::Cache;
6 tie %cache, 'Tie::Cache', 100, { Debug => 1 };
7 tie %cache2, 'Tie::Cache', { MaxCount => 100, MaxBytes => 50000 };
8 tie %cache3, 'Tie::Cache', 100, { Debug => 1 , WriteSync => 0};
9
10 # Options ##################################################################
11 #
12 # Debug => 0 - DEFAULT, no debugging output
13 # 1 - prints cache statistics upon destroying
14 # 2 - prints detailed debugging info
15 #
16 # MaxCount => Maximum entries in cache.
17 #
18 # MaxBytes => Maximum bytes taken in memory for cache based on approximate
19 # size of total cache structure in memory
20 #
21 # There is approximately 240 bytes used per key/value pair in the cache for
22 # the cache data structures, so a cache of 5000 entries would take
23 # at approximately 1.2M plus the size of the data being cached.
24 #
25 # MaxSize => Maximum size of each cache entry. Larger entries are not cached.
26 # This helps prevent much of the cache being flushed when
27 # you set an exceptionally large entry. Defaults to MaxBytes/10
28 #
29 # WriteSync => 1 - DEFAULT, write() when data is dirtied for
30 # TRUE CACHE (see below)
31 # 0 - write() dirty data as late as possible, when leaving
32 # cache, or when cache is being DESTROY'd
33 #
34 ############################################################################
35
36 # cache supports normal tied hash functions
37 $cache{1} = 2; # STORE
38 print "$cache{1}\n"; # FETCH
39
40 # FIRSTKEY, NEXTKEY
41 while(($k, $v) = each %cache) { print "$k: $v\n"; }
42
43 delete $cache{1}; # DELETE
44 %cache = (); # CLEAR
45
46 DESCRIPTION
47 This module implements a least recently used (LRU) cache in memory through a
48 tie interface. Any time data is stored in the tied hash, that key/value pair
49 has an entry time associated with it, and as the cache fills up, those
50 members of the cache that are the oldest are removed to make room for new
51 entries.
52
53 So, the cache only "remembers" the last written entries, up to the size of
54 the cache. This can be especially useful if you access great amounts of
55 data, but only access a minority of the data a majority of the time.
56
57 The implementation is a hash, for quick lookups, overlaying a doubly linked
58 list for quick insertion and deletion. On a WinNT PII 300, writes to the
59 hash were done at a rate 3100 per second, and reads from the hash at 6300
60 per second. Work has been done to optimize refreshing cache entries that are
61 frequently read from, code like $cache{entry}, which moves the entry to the
62 end of the linked list internally.
63
64 INSTALLATION
65 Tie::Cache installs easily using the make or nmake commands as shown below.
66 Otherwise, just copy Cache.pm to $PERLLIB/site/Tie
67
68 > perl Makefile.PL
69 > make
70 > make test
71 > make install
72
73 * use nmake for win32
74 ** you can also just copy Cache.pm to $perllib/Tie
75
76 BENCMARKS
77 There is another simpler LRU cache implementation in CPAN, Tie::Cache::LRU,
78 which has the same basic size limiting functionality, and for this
79 functionality, the exact same interface.
80
81 Through healthy competition, Michael G Schwern got Tie::Cache::LRU mostly
82 faster than Tie::Cache on reads & writes:
83
84 Cache Size 5000 Tie::Cache 0.17 Tie::Cache::LRU 20110205.00
85 10000 Writes 0.63 CPU sec 0.47 CPU sec
86 40000 Reads 0.79 CPU sec 0.71 CPU sec
87 10000 Deletes 0.23 CPU sec 0.26 CPU sec
88
89 Unless you are using TRUE CACHE or MaxBytes functionality, using
90 Tie::Cache::LRU could be an easy replacement for Tie::Cache.
91
92 OTOH one nice thing about this module is its lack of external module
93 dependencies!
94
95 TRUE CACHE
96 To use class as a true cache, which acts as the sole interface for some data
97 set, subclass the real cache off Tie::Cache, with @ISA = qw( 'Tie::Cache' )
98 notation. Then override the read() method for behavior when there is a cache
99 miss, and the write() method for behavior when the cache's data changes.
100
101 When WriteSync is 1 or TRUE (DEFAULT), write() is called immediately when
102 data in the cache is modified. If set to 0, data that has been modified in
103 the cache gets written out when the entries are deleted or during the
104 DESTROY phase of the cache object, usually at the end of a script.
105
106 To have the dirty data write() periodically while WriteSync is set to 0,
107 there is a flush() cache API call that will flush the dirty writes in this
108 way. Just call the flush() API like:
109
110 my $write_flush_count = tied(%cache)->flush();
111
112 The flush() API was added in the .17 release thanks to Rob Bloodgood.
113
114 TRUE CACHE EXAMPLE
115 use Tie::Cache;
116
117 # personalize the Tie::Cache object, by inheriting from it
118 package My::Cache;
119 @ISA = qw(Tie::Cache);
120
121 # override the read() and write() member functions
122 # these tell the cache what to do with a cache miss or flush
123 sub read {
124 my($self, $key) = @_;
125 print "cache miss for $key, read() data\n";
126 rand() * $key;
127 }
128 sub write {
129 my($self, $key, $value) = @_;
130 print "flushing [$key, $value] from cache, write() data\n";
131 }
132
133 my $cache_size = $ARGV[0] || 2;
134 my $num_to_cache = $ARGV[1] || 4;
135 my $Debug = $ARGV[2] || 1;
136
137 tie %cache, 'My::Cache', $cache_size, {Debug => $Debug};
138
139 # load the cache with new data, each through its contents,
140 # and then reload in reverse order.
141 for(1..$num_to_cache) { print "read data $_: $cache{$_}\n" }
142 while(my($k, $v) = each %cache) { print "each data $k: $v\n"; }
143 for(my $i=$num_to_cache; $i>0; $i--) { print "read data $i: $cache{$i}\n"; }
144
145 # flush writes now, trivial use since will happen in DESTROY() anyway
146 tied(%cache)->flush();
147
148 # clear cache in 2 ways, write will flush out to disk
149 %cache = ();
150 undef %cache;
151
152 NOTES
153 Many thanks to all those who helped me make this module a reality,
154 including:
155
156 :) Tom Hukins who provided me insight and motivation for
157 finishing this module.
158 :) Jamie McCarthy, for trying to make Tie::Cache be all
159 that it can be.
160 :) Rob Fugina who knows how to "TRULY CACHE".
161 :) Rob Bloodgood, for the TRUE CACHE flush() API
162
163 AUTHOR
164 Please send any questions or comments to Joshua Chamas at
165 [email protected]
166
167 COPYRIGHT
168 Copyright (c) 1999-2012 Joshua Chamas, Chamas Enterprises Inc. Sponsored by
169 development on NodeWorks http://nodeworks.com and Web Test.org
170 http://web-test.org
171
172 All rights reserved. This program is free software; you can redistribute it
173 and/or modify it under the same terms as Perl itself.
174