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

NAME

6       Cache - the Cache interface
7

DESCRIPTION

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
14       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

USAGE

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
24       Using a cache is simple.  Here is some very simple sample code for
25       instantiating and using a file system based cache.
26
27         use Cache::File;
28
29         my $cache = Cache::File->new( cache_root => '/tmp/cacheroot' );
30         my $customer = $cache->get( $name );
31
32         unless ($customer) {
33             $customer = get_customer_from_db( $name );
34             $cache->set( $name, $customer, '10 minutes' );
35         }
36
37         return $customer;
38
39       Of course, far more powerful methods are available for accessing cached
40       data.  Also see the TIE INTERFACE below.
41

METHODS

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
49       $c->purge()
50           Remove all expired data from the cache.
51
52       $c->clear()
53           Remove all entries from the cache - regardless of their expiry
54           time.
55
56       my $num = $c->count()
57           Returns the number of entries in the cache.
58
59       my $size = $c->size()
60           Returns the size (in bytes) of the cache.
61

PROPERTIES

63       When a cache is constructed these properties can be supplied as options
64       to the new() method.
65
66       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
70            my $time = $c->default_expires();
71            $c->set_default_expires( $expiry );
72
73       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
77           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
82           The strategies 'Cache::RemovalStrategy::LRU' and
83           'Cache::RemovalStrategy::FIFO' are available by default.
84
85            my $strategy = $c->removal_strategy();
86
87       size_limit
88           The size limit for the cache.
89
90            my $limit = $c->size_limit();
91
92       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
97            my $limit = $c->load_callback();
98            $c->set_load_callback($callback_func);
99
100       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
105            my $limit = $c->validate_callback();
106            $c->set_validate_callback($callback_func);
107

SHORTCUT METHODS

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
114       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

TIE INTERFACE

128         tie %hash, 'Cache::File', { cache_root => $tempdir };
129
130         $hash{'key'} = 'some data';
131         $data = $hash{'key'};
132
133       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
138       The tie interface is especially useful with the load_callback to
139       automatically populate the hash.
140

REMOVAL STRATEGY METHODS

142       These methods are only for use internally (by concrete Cache
143       implementations).
144
145       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
153       my $size = $c->remove_oldest()
154           Removes the oldest entry in the cache and returns its size.
155
156       my $size = $c->remove_stalest()
157           Removes the 'stalest' (least used) object in the cache and returns
158           its size.
159
160       $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

UTILITY METHODS

169       These methods are only for use internally (by concrete Cache
170       implementations).
171
172       my $time = Cache::Canonicalize_Expiration_Time($timespec)
173           Converts a timespec as described for Cache::Entry::set_expiry()
174           into a unix time.
175

SEE ALSO

177       Cache::Entry, Cache::File, Cache::RemovalStrategy
178

DIFFERENCES FROM CACHE::CACHE

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
185       The semantics of use are very similar to Cache::Cache, with the
186       following exceptions:
187
188       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

AUTHOR

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
215       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
219       $Id: Cache.pm,v 1.7 2006/01/31 15:23:58 caleishm Exp $
220
221
222
223perl v5.32.0                      2020-07-28                          Cache(3)
Impressum