1Cache(3)              User Contributed Perl Documentation             Cache(3)
2
3
4

NAME

6       Tie::Cache - LRU Cache in Memory
7

SYNOPSIS

9        use Tie::Cache;
10        tie %cache, 'Tie::Cache', 100, { Debug => 1 };
11        tie %cache2, 'Tie::Cache', { MaxCount => 100, MaxBytes => 50000 };
12        tie %cache3, 'Tie::Cache', 100, { Debug => 1 , WriteSync => 0};
13
14        # Options ##################################################################
15        #
16        # Debug =>      0 - DEFAULT, no debugging output
17        #               1 - prints cache statistics upon destroying
18        #               2 - prints detailed debugging info
19        #
20        # MaxCount =>   Maximum entries in cache.
21        #
22        # MaxBytes =>   Maximum bytes taken in memory for cache based on approximate
23        #               size of total cache structure in memory
24        #
25        #               There is approximately 240 bytes used per key/value pair in the cache for
26        #               the cache data structures, so a cache of 5000 entries would take
27        #               at approximately 1.2M plus the size of the data being cached.
28        #
29        # MaxSize  =>   Maximum size of each cache entry. Larger entries are not cached.
30        #                   This helps prevent much of the cache being flushed when
31        #                   you set an exceptionally large entry.  Defaults to MaxBytes/10
32        #
33        # WriteSync =>  1 - DEFAULT, write() when data is dirtied for
34        #                   TRUE CACHE (see below)
35        #               0 - write() dirty data as late as possible, when leaving
36        #                   cache, or when cache is being DESTROY'd
37        #
38        ############################################################################
39
40        # cache supports normal tied hash functions
41        $cache{1} = 2;       # STORE
42        print "$cache{1}\n"; # FETCH
43
44        # FIRSTKEY, NEXTKEY
45        while(($k, $v) = each %cache) { print "$k: $v\n"; }
46
47        delete $cache{1};    # DELETE
48        %cache = ();         # CLEAR
49

DESCRIPTION

51       This module implements a least recently used (LRU) cache in memory
52       through a tie interface.  Any time data is stored in the tied hash,
53       that key/value pair has an entry time associated with it, and as the
54       cache fills up, those members of the cache that are the oldest are
55       removed to make room for new entries.
56
57       So, the cache only "remembers" the last written entries, up to the size
58       of the cache.  This can be especially useful if you access great
59       amounts of data, but only access a minority of the data a majority of
60       the time.
61
62       The implementation is a hash, for quick lookups, overlaying a doubly
63       linked list for quick insertion and deletion.  On a WinNT PII 300,
64       writes to the hash were done at a rate 3100 per second, and reads from
65       the hash at 6300 per second.  Work has been done to optimize refreshing
66       cache entries that are frequently read from, code like $cache{entry},
67       which moves the entry to the end of the linked list internally.
68

INSTALLATION

70       Tie::Cache installs easily using the make or nmake commands as shown
71       below.  Otherwise, just copy Cache.pm to $PERLLIB/site/Tie
72
73               > perl Makefile.PL
74               > make
75               > make test
76               > make install
77
78               * use nmake for win32
79               ** you can also just copy Cache.pm to $perllib/Tie
80

BENCMARKS

82       There is another simpler LRU cache implementation in CPAN,
83       Tie::Cache::LRU, which has the same basic size limiting functionality,
84       and for this functionality, the exact same interface.
85
86       Through healthy competition, Michael G Schwern got Tie::Cache::LRU
87       mostly faster than Tie::Cache on reads & writes:
88
89        Cache Size 5000       Tie::Cache 0.17  Tie::Cache::LRU 20110205.00
90        10000 Writes             0.63 CPU sec          0.47 CPU sec
91        40000 Reads              0.79 CPU sec          0.71 CPU sec
92        10000 Deletes            0.23 CPU sec          0.26 CPU sec
93
94       Unless you are using TRUE CACHE or MaxBytes functionality, using
95       Tie::Cache::LRU could be an easy replacement for Tie::Cache.
96
97       OTOH one nice thing about this module is its lack of external module
98       dependencies!
99

TRUE CACHE

101       To use class as a true cache, which acts as the sole interface for some
102       data set, subclass the real cache off Tie::Cache, with @ISA = qw(
103       'Tie::Cache' ) notation.  Then override the read() method for behavior
104       when there is a cache miss, and the write() method for behavior when
105       the cache's data changes.
106
107       When WriteSync is 1 or TRUE (DEFAULT), write() is called immediately
108       when data in the cache is modified.  If set to 0, data that has been
109       modified in the cache gets written out when the entries are deleted or
110       during the DESTROY phase of the cache object, usually at the end of a
111       script.
112
113       To have the dirty data write() periodically while WriteSync is set to
114       0, there is a flush() cache API call that will flush the dirty writes
115       in this way.  Just call the flush() API like:
116
117         my $write_flush_count = tied(%cache)->flush();
118
119       The flush() API was added in the .17 release thanks to Rob Bloodgood.
120

TRUE CACHE EXAMPLE

122        use Tie::Cache;
123
124        # personalize the Tie::Cache object, by inheriting from it
125        package My::Cache;
126        @ISA = qw(Tie::Cache);
127
128        # override the read() and write() member functions
129        # these tell the cache what to do with a cache miss or flush
130        sub read {
131           my($self, $key) = @_;
132           print "cache miss for $key, read() data\n";
133           rand() * $key;
134        }
135        sub write {
136           my($self, $key, $value) = @_;
137           print "flushing [$key, $value] from cache, write() data\n";
138        }
139
140        my $cache_size   = $ARGV[0] || 2;
141        my $num_to_cache = $ARGV[1] || 4;
142        my $Debug = $ARGV[2] || 1;
143
144        tie %cache, 'My::Cache', $cache_size, {Debug => $Debug};
145
146        # load the cache with new data, each through its contents,
147        # and then reload in reverse order.
148        for(1..$num_to_cache) { print "read data $_: $cache{$_}\n" }
149        while(my($k, $v) = each %cache) { print "each data $k: $v\n"; }
150        for(my $i=$num_to_cache; $i>0; $i--) { print "read data $i: $cache{$i}\n"; }
151
152        # flush writes now, trivial use since will happen in DESTROY() anyway
153        tied(%cache)->flush();
154
155        # clear cache in 2 ways, write will flush out to disk
156        %cache = ();
157        undef %cache;
158

NOTES

160       Many thanks to all those who helped me make this module a reality,
161       including:
162
163               :) Tom Hukins who provided me insight and motivation for
164                  finishing this module.
165               :) Jamie McCarthy, for trying to make Tie::Cache be all
166                  that it can be.
167               :) Rob Fugina who knows how to "TRULY CACHE".
168               :) Rob Bloodgood, for the TRUE CACHE flush() API
169

AUTHOR

171       Please send any questions or comments to Joshua Chamas at
172       chamas@alumni.stanford.org
173
175       Copyright (c) 1999-2012 Joshua Chamas, Chamas Enterprises Inc.
176       Sponsored by development on NodeWorks http://nodeworks.com and Web
177       Test.org http://web-test.org
178
179       All rights reserved. This program is free software; you can
180       redistribute it and/or modify it under the same terms as Perl itself.
181
182
183
184perl v5.30.1                      2020-01-30                          Cache(3)
Impressum