1Cache(3) User Contributed Perl Documentation Cache(3)
2
6 Cache - the Cache interface
7
9 The Cache modules are designed to assist a developer in persisting data
10 for a specified period of time. Often these modules are used in web
11 applications to store data locally to save repeated and redundant
12 expensive calls to remote machines or databases.
13 The Cache interface is implemented by derived classes that store cached
15 data in different manners (such as as files on a filesystem, or in mem‐
16 ory).
17
19 To use the Cache system, a cache implementation must be chosen to suit
20 your needs. The most common is Cache::File, which is suitable for
21 sharing data between multiple invocations and even between concurrent
22 processes.
23 Using a cache is simple. Here is some very simple sample code for
25 instantiating and using a file system based cache.
26 use Cache::File;
28 my $cache = Cache::File->new( cache_root => '/tmp/cacheroot' );
30 my $customer = $cache->get( $name );
31 unless ($customer) {
33 $customer = get_customer_from_db( $name );
34 $cache->set( $name, $customer, '10 minutes' );
35 }
36 return $customer;
38 Of course, far more powerful methods are available for accessing cached
40 data. Also see the TIE INTERFACE below.
41
43 my $cache_entry = $c->entry( $key )
44 Return a 'Cache::Entry' object for the given key. This object can
45 then be used to manipulate the cache entry in various ways. The
46 key can be any scalar string that will uniquely identify an entry
47 in the cache.
48 $c->purge()
50 Remove all expired data from the cache.
51 $c->clear()
53 Remove all entries from the cache - regardless of their expiry
54 time.
55 my $num = $c->count()
57 Returns the number of entries in the cache.
58 my $size = $c->size()
60 Returns the size (in bytes) of the cache.
61
63 When a cache is constructed these properties can be supplied as options
64 to the new() method.
65 default_expires
67 The current default expiry time for new entries into the cache.
68 This property can also be reset at any time.
69 my $time = $c->default_expires();
71 $c->set_default_expires( $expiry );
72 removal_strategy
74 The removal strategy object for the cache. This is used to remove
75 object from the cache in order to maintain the cache size limit.
76 When setting the removal strategy in new(), the name of a strategy
78 package or a blessed strategy object reference should be provided
79 (in the former case an object is constructed by calling the new()
80 method of the named package).
81 The strategies 'Cache::RemovalStrategy::LRU' and 'Cache::Removal‐
83 Strategy::FIFO' are available by default.
84 my $strategy = $c->removal_strategy();
86 size_limit
88 The size limit for the cache.
89 my $limit = $c->size_limit();
91 load_callback
93 The load callback for the cache. This may be set to a function
94 that will get called anytime a 'get' is issued for data that does
95 not exist in the cache.
96 my $limit = $c->load_callback();
98 $c->set_load_callback($callback_func);
99 validate_callback
101 The validate callback for the cache. This may be set to a function
102 that will get called anytime a 'get' is issued for data that does
103 not exist in the cache.
104 my $limit = $c->validate_callback();
106 $c->set_validate_callback($callback_func);
107
109 These methods all have counterparts in the Cache::Entry package, but
110 are provided here as shortcuts. They all default to just wrappers that
111 do '$c->entry($key)->method_name()'. For documentation, please refer
112 to Cache::Entry.
113 my $bool = $c->exists( $key )
115 $c->set( $key, $data, [ $expiry ] )
116 my $data = $c->get( $key )
117 my $data = $c->size( $key )
118 $c->remove( $key )
119 $c->expiry( $key )
120 $c->set_expiry( $key, $time )
121 $c->handle( $key, [$mode, [$expiry] ] )
122 $c->validity( $key )
123 $c->set_validity( $key, $data )
124 $c->freeze( $key, $data, [ $expiry ] )
125 $c->thaw( $key )
126
128 tie %hash, 'Cache::File', { cache_root => $tempdir };
129 $hash{'key'} = 'some data';
131 $data = $hash{'key'};
132 The Cache classes can be used via the tie interface, as shown in the
134 synopsis. This allows the cache to be accessed via a hash. All the
135 standard methods for accessing the hash are supported , with the excep‐
136 tion of the 'keys' or 'each' call.
137 The tie interface is especially useful with the load_callback to auto‐
139 matically populate the hash.
140
142 These methods are only for use internally (by concrete Cache implemen‐
143 tations).
144 These methods define the interface by which the removal strategy object
146 can manipulate the cache (the Cache is the 'context' of the strategy).
147 By default, methods need to be provided to remove the oldest or stalest
148 objects in the cache - thus allowing support for the default FIFO and
149 LRU removal strategies. All derived Cache implementations should sup‐
150 port these methods and may also introduce additional methods (and addi‐
151 tional removal strategies to match).
152 my $size = $c->remove_oldest()
154 Removes the oldest entry in the cache and returns its size.
155 my $size = $c->remove_stalest()
157 Removes the 'stalest' (least used) object in the cache and returns
158 its size.
159 $c->check_size( $size )
161 This method isn't actually part of the strategy interface, nor does
162 it need to be defined by Cache implementations. Instead it should
163 be called by implementations whenever the size of the cache
164 increases. It will take care of checking the size limit and invok‐
165 ing the removal strategy if required. The size argument should be
166 the new size of the cache.
167
169 These methods are only for use internally (by concrete Cache implemen‐
170 tations).
171 my $time = Cache::Canonicalize_Expiration_Time($timespec)
173 Converts a timespec as described for Cache::Entry::set_expiry()
174 into a unix time.
175
177 Cache::Entry, Cache::File, Cache::RemovalStrategy
178
180 The Cache modules are a total redesign and reimplementation of
181 Cache::Cache and thus not directly compatible. It would be, however,
182 quite possible to write a wrapper module that provides an identical
183 interface to Cache::Cache.
184 The semantics of use are very similar to Cache::Cache, with the follow‐
186 ing exceptions:
187 The get/set methods DO NOT serialize complex data types. Use
189 freeze/thaw instead (but read the notes in Cache::Entry).
190 The get_object / set_object methods are not available, but have
191 been superseded by the more flexible entry method and Cache::Entry
192 class.
193 There is no concept of 'namespace' in the basic cache interface,
194 although implementations (eg. Cache::Memory) may choose to provide
195 them. For instance, File::Cache does not provide this - but dif‐
196 ferent namespaces can be created by varying cache_root.
197 In the current Cache implementations purging is done automatically
198 - there is no need to explicitly enable auto purge on get/set. The
199 purging algorithm is no longer implemented in the base Cache class,
200 but is left up to the implementations and may thus be implemented
201 in the most efficient way for the storage medium.
202 Cache::SharedMemory is not yet available.
203 Cache::File no longer supports separate masks for entries and
204 directories. It is not a very secure configuration and presents
205 numerous issues for cache consistency and is hence depricated.
206 There is still some work to be done to ensure cache consistency
207 between accesses by different users.
208
210 Chris Leishman <chris@leishman.org>
211 Based on work by DeWitt Clinton <dewitt@unto.net>
212
214 Copyright (C) 2003-2006 Chris Leishman. All Rights Reserved.
215 This module is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
217 KIND, either expressed or implied. This program is free software; you
218 can redistribute or modify it under the same terms as Perl itself.
219 $Id: Cache.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $
221perl v5.8.8 2006-01-31 Cache(3)