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 files on a filesystem, or in
16 memory).
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
83 'Cache::RemovalStrategy::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
136 exception of the 'keys' or 'each' call.
137 The tie interface is especially useful with the load_callback to
139 automatically populate the hash.
140
142 These methods are only for use internally (by concrete Cache
143 implementations).
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
150 support these methods and may also introduce additional methods (and
151 additional 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
165 invoking the removal strategy if required. The size argument
166 should be the new size of the cache.
167
169 These methods are only for use internally (by concrete Cache
170 implementations).
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
186 following 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 been
191 superseded by the more flexible entry method and Cache::Entry class.
192 There is no concept of 'namespace' in the basic cache interface,
193 although implementations (eg. Cache::Memory) may choose to provide
194 them. For instance, File::Cache does not provide this - but different
195 namespaces can be created by varying cache_root.
196 In the current Cache implementations purging is done automatically -
197 there is no need to explicitly enable auto purge on get/set. The
198 purging algorithm is no longer implemented in the base Cache class, but
199 is left up to the implementations and may thus be implemented in the
200 most efficient way for the storage medium.
201 Cache::SharedMemory is not yet available.
202 Cache::File no longer supports separate masks for entries and
203 directories. It is not a very secure configuration and presents
204 numerous issues for cache consistency and is hence deprecated. There
205 is still some work to be done to ensure cache consistency between
206 accesses by different users.
207
209 Chris Leishman <chris@leishman.org>
210 Based on work by DeWitt Clinton <dewitt@unto.net>
211
213 Copyright (C) 2003-2006 Chris Leishman. All Rights Reserved.
214 This module is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
216 KIND, either expressed or implied. This program is free software; you
217 can redistribute or modify it under the same terms as Perl itself.
218 $Id: Cache.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $
220perl v5.34.0 2021-07-22 Cache(3)