Cache::Cache(3pm)

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

NAME

6       Cache::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.  People have also been
13       known to use Cache::Cache for its straightforward interface in sharing
14       data between runs of an application or invocations of a CGI-style
15       script or simply as an easy to use abstraction of the filesystem or
16       shared memory.
17
18       The Cache::Cache interface is implemented by classes that support the
19       get, set, remove, size, purge, and clear instance methods and their
20       corresponding static methods for persisting data across method calls.
21

USAGE

23       First, choose the best type of cache implementation for your needs.
24       The simplest cache is the MemoryCache, which is suitable for applica‐
25       tions that are serving multiple sequential requests, and wish to avoid
26       making redundant expensive queries, such as an Apache/mod_perl applica‐
27       tion talking to a database.  If you wish to share that data between
28       processes, then perhaps the SharedMemoryCache is appropriate, although
29       its behavior is tightly bound to the underlying IPC mechanism, which
30       varies from system to system, and is unsuitable for large objects or
31       large numbers of objects.  When the SharedMemoryCache is not accept‐
32       able, then FileCache offers all of the same functionality with similar
33       performance metrics, and it is not limited in terms of the number of
34       objects or their size.  If you wish to maintain a strict limit on the
35       size of a file system based cache, then the SizeAwareFileCache is the
36       way to go.  Similarly, the SizeAwareMemoryCache and the SizeAware‐
37       SharedMemoryCache add size management functionality to the MemoryCache
38       and SharedMemoryCache classes respectively.
39
40       Using a cache is simple.  Here is some sample code for instantiating
41       and using a file system based cache.
42
43         use Cache::FileCache;
44
45         my $cache = new Cache::FileCache( );
46
47         my $customer = $cache->get( $name );
48
49         if ( not defined $customer )
50         {
51           $customer = get_customer_from_db( $name );
52           $cache->set( $name, $customer, "10 minutes" );
53         }
54
55         return $customer;
56

CONSTANTS

58       $EXPIRES_NEVER
59           The item being set in the cache will never expire.
60
61       $EXPIRES_NOW
62           The item being set in the cache will expire immediately.
63

METHODS

65       Clear( )
66           Remove all objects from all caches of this type.
67
68       Purge( )
69           Remove all objects that have expired from all caches of this type.
70
71       Size( )
72           Returns the total size of all objects in all caches of this type.
73
74       new( $options_hash_ref )
75           Construct a new instance of a Cache::Cache. $options_hash_ref is a
76           reference to a hash containing configuration options; see the sec‐
77           tion OPTIONS below.
78
79       clear(  )
80           Remove all objects from the namespace associated with this cache
81           instance.
82
83       get( $key )
84           Returns the data associated with $key.
85
86       get_object( $key )
87           Returns the underlying Cache::Object object used to store the
88           cached data associated with $key.  This will not trigger a removal
89           of the cached object even if the object has expired.
90
91       purge(  )
92           Remove all objects that have expired from the namespace associated
93           with this cache instance.
94
95       remove( $key )
96           Delete the data associated with the $key from the cache.
97
98       set( $key, $data, [$expires_in] )
99           Associates $data with $key in the cache. $expires_in indicates the
100           time in seconds until this data should be erased, or the constant
101           $EXPIRES_NOW, or the constant $EXPIRES_NEVER.  Defaults to
102           $EXPIRES_NEVER.  This variable can also be in the extended format
103           of "[number] [unit]", e.g., "10 minutes".  The valid units are s,
104           second, seconds, sec, m, minute, minutes, min, h, hour, hours, d,
105           day, days, w, week, weeks, M, month, months, y, year, and years.
106           Additionally, $EXPIRES_NOW can be represented as "now" and
107           $EXPIRES_NEVER can be represented as "never".
108
109       set_object( $key, $object )
110           Associates $key with Cache::Object $object.  Using set_object (as
111           opposed to set) does not trigger an automatic removal of expired
112           objects.
113
114       size(  )
115           Returns the total size of all objects in the namespace associated
116           with this cache instance.
117
118       get_namespaces( )
119           Returns all the namespaces associated with this type of cache.
120

OPTIONS

122       The options are set by passing in a reference to a hash containing any
123       of the following keys:
124
125       namespace
126           The namespace associated with this cache.  Defaults to "Default" if
127           not explicitly set.
128
129       default_expires_in
130           The default expiration time for objects place in the cache.
131           Defaults to $EXPIRES_NEVER if not explicitly set.
132
133       auto_purge_interval
134           Sets the auto purge interval.  If this option is set to a particu‐
135           lar time ( in the same format as the expires_in ), then the purge(
136           ) routine will be called during the first set after the interval
137           expires.  The interval will then be reset.
138
139       auto_purge_on_set
140           If this option is true, then the auto purge interval routine will
141           be checked on every set.
142
143       auto_purge_on_get
144           If this option is true, then the auto purge interval routine will
145           be checked on every get.  This is probably not the desired behav‐
146           ior, as the purge could be a very expensive operation.
147

PROPERTIES

149       (get⎪set)_namespace( )
150           The namespace of this cache instance
151
152       get_default_expires_in( )
153           The default expiration time for objects placed in this cache
154           instance
155
156       get_keys( )
157           The list of keys specifying objects in the namespace associated
158           with this cache instance
159
160       get_identifiers( )
161           This method has been deprecated in favor of get_keys( ).
162
163       (get⎪set)_auto_purge_interval( )
164           Accesses the auto purge interval.  If this option is set to a par‐
165           ticular time ( in the same format as the expires_in ), then the
166           purge( ) routine will be called during the first get after the
167           interval expires.  The interval will then be reset.
168
169       (get⎪set)_auto_purge_on_set( )
170           If this property is true, then the auto purge interval routine will
171           be checked on every set.
172
173       (get⎪set)_auto_purge_on_get( )
174           If this property is true, then the auto purge interval routine will
175           be checked on every get.
176

AUTHOR

182       Original author: DeWitt Clinton <dewitt@unto.net>
183
184       Last author:     $Author: dclinton $
185
186       Copyright (C) 2001-2003 DeWitt Clinton
187
188
189
190perl v5.8.8                       2003-04-15                   Cache::Cache(3)