File Coverage

blib/lib/Cache/Cache.pm

Criterion	Covered	Total	%
statement	9	9	100.0
branch			n/a
condition			n/a
subroutine	3	3	100.0
pod			n/a
total	12	12	100.0

line	stmt	sub	time	code
1				#####################################################################
2				# $Id: Cache.pm,v 1.43 2005/07/13 22:29:33 dclinton Exp $
3				# Copyright (C) 2001-2003 DeWitt Clinton All Rights Reserved
4				#
5				# Software distributed under the License is distributed on an "AS
6				# IS" basis, WITHOUT WARRANTY OF ANY KIND, either expressed or
7				# implied. See the License for the specific language governing
8				# rights and limitations under the License.
9				######################################################################
10
11
12				package Cache::Cache;
13
14
15	5	5	82	use strict;
	5		65
	5		86
16	5	5	100	use vars qw( @ISA @EXPORT_OK $VERSION $EXPIRES_NOW $EXPIRES_NEVER );
	5		45
	5		82
17	5	5	74	use Exporter;
	5		45
	5		130
18
19				@ISA = qw( Exporter );
20
21				@EXPORT_OK = qw( $VERSION $EXPIRES_NOW $EXPIRES_NEVER );
22
23				$VERSION = "1.05";
24				$EXPIRES_NOW = 'now';
25				$EXPIRES_NEVER = 'never';
26
27
28				sub Clear;
29
30				sub Purge;
31
32				sub Size;
33
34				sub new;
35
36				sub clear;
37
38				sub get;
39
40				sub get_object;
41
42				sub purge;
43
44				sub remove;
45
46				sub set;
47
48				sub set_object;
49
50				sub size;
51
52				sub get_default_expires_in;
53
54				sub get_namespace;
55
56				sub set_namespace;
57
58				sub get_keys;
59
60				sub get_auto_purge_interval;
61
62				sub set_auto_purge_interval;
63
64				sub get_auto_purge_on_get;
65
66				sub set_auto_purge_on_set;
67
68				sub get_namespaces;
69
70				sub get_identifiers; # deprecated
71
72
73				1;
74
75
76				__END__
77
78
79				=pod
80
81				=head1 NAME
82
83				Cache::Cache -- the Cache interface.
84
85				=head1 DESCRIPTION
86
87				The Cache modules are designed to assist a developer in persisting
88				data for a specified period of time. Often these modules are used in
89				web applications to store data locally to save repeated and redundant
90				expensive calls to remote machines or databases. People have also
91				been known to use Cache::Cache for its straightforward interface in
92				sharing data between runs of an application or invocations of a
93				CGI-style script or simply as an easy to use abstraction of the
94				filesystem or shared memory.
95
96				The Cache::Cache interface is implemented by classes that support the
97				get, set, remove, size, purge, and clear instance methods and their
98				corresponding static methods for persisting data across method calls.
99
100				=head1 USAGE
101
102				First, choose the best type of cache implementation for your needs.
103				The simplest cache is the MemoryCache, which is suitable for
104				applications that are serving multiple sequential requests, and wish
105				to avoid making redundant expensive queries, such as an
106				Apache/mod_perl application talking to a database. If you wish to
107				share that data between processes, then perhaps the SharedMemoryCache
108				is appropriate, although its behavior is tightly bound to the
109				underlying IPC mechanism, which varies from system to system, and is
110				unsuitable for large objects or large numbers of objects. When the
111				SharedMemoryCache is not acceptable, then FileCache offers all of the
112				same functionality with similar performance metrics, and it is not
113				limited in terms of the number of objects or their size. If you wish
114				to maintain a strict limit on the size of a file system based cache,
115				then the SizeAwareFileCache is the way to go. Similarly, the
116				SizeAwareMemoryCache and the SizeAwareSharedMemoryCache add size
117				management functionality to the MemoryCache and SharedMemoryCache
118				classes respectively.
119
120				Using a cache is simple. Here is some sample code for instantiating
121				and using a file system based cache.
122
123				use Cache::FileCache;
124
125				my $cache = new Cache::FileCache( );
126
127				my $customer = $cache->get( $name );
128
129				if ( not defined $customer )
130				{
131				$customer = get_customer_from_db( $name );
132				$cache->set( $name, $customer, "10 minutes" );
133				}
134
135				return $customer;
136
137
138				=head1 CONSTANTS
139
140				=over
141
142				=item I<$EXPIRES_NEVER>
143
144				The item being set in the cache will never expire.
145
146				=item I<$EXPIRES_NOW>
147
148				The item being set in the cache will expire immediately.
149
150				=back
151
152				=head1 METHODS
153
154				=over
155
156				=item B<Clear( )>
157
158				Remove all objects from all caches of this type.
159
160				=item B<Purge( )>
161
162				Remove all objects that have expired from all caches of this type.
163
164				=item B<Size( )>
165
166				Returns the total size of all objects in all caches of this type.
167
168				=item B<new( $options_hash_ref )>
169
170				Construct a new instance of a Cache::Cache. I<$options_hash_ref> is a
171				reference to a hash containing configuration options; see the section
172				OPTIONS below.
173
174				=item B<clear( )>
175
176				Remove all objects from the namespace associated with this cache instance.
177
178				=item B<get( $key )>
179
180				Returns the data associated with I<$key>.
181
182				=item B<get_object( $key )>
183
184				Returns the underlying Cache::Object object used to store the cached
185				data associated with I<$key>. This will not trigger a removal
186				of the cached object even if the object has expired.
187
188				=item B<purge( )>
189
190				Remove all objects that have expired from the namespace associated
191				with this cache instance.
192
193				=item B<remove( $key )>
194
195				Delete the data associated with the I<$key> from the cache.
196
197				=item B<set( $key, $data, [$expires_in] )>
198
199				Associates I<$data> with I<$key> in the cache. I<$expires_in>
200				indicates the time in seconds until this data should be erased, or the
201				constant $EXPIRES_NOW, or the constant $EXPIRES_NEVER. Defaults to
202				$EXPIRES_NEVER. This variable can also be in the extended format of
203				"[number] [unit]", e.g., "10 minutes". The valid units are s, second,
204				seconds, sec, m, minute, minutes, min, h, hour, hours, d, day, days, w,
205				week, weeks, M, month, months, y, year, and years. Additionally,
206				$EXPIRES_NOW can be represented as "now" and $EXPIRES_NEVER can be
207				represented as "never".
208
209				=item B<set_object( $key, $object )>
210
211				Associates I<$key> with Cache::Object I<$object>. Using set_object
212				(as opposed to set) does not trigger an automatic removal of expired
213				objects.
214
215				=item B<size( )>
216
217				Returns the total size of all objects in the namespace associated with
218				this cache instance.
219
220				=item B<get_namespaces( )>
221
222				Returns all the namespaces associated with this type of cache.
223
224				=back
225
226				=head1 OPTIONS
227
228				The options are set by passing in a reference to a hash containing any
229				of the following keys:
230
231				=over
232
233				=item I<namespace>
234
235				The namespace associated with this cache. Defaults to "Default" if
236				not explicitly set.
237
238				=item I<default_expires_in>
239
240				The default expiration time for objects place in the cache. Defaults
241				to $EXPIRES_NEVER if not explicitly set.
242
243				=item I<auto_purge_interval>
244
245				Sets the auto purge interval. If this option is set to a particular
246				time ( in the same format as the expires_in ), then the purge( )
247				routine will be called during the first set after the interval
248				expires. The interval will then be reset.
249
250				=item I<auto_purge_on_set>
251
252				If this option is true, then the auto purge interval routine will be
253				checked on every set.
254
255				=item I<auto_purge_on_get>
256
257				If this option is true, then the auto purge interval routine will be
258				checked on every get. This is probably not the desired behavior, as
259				the purge could be a very expensive operation.
260
261
262				=back
263
264				=head1 PROPERTIES
265
266				=over
267
268				=item B<(get\|set)_namespace( )>
269
270				The namespace of this cache instance
271
272				=item B<get_default_expires_in( )>
273
274				The default expiration time for objects placed in this cache instance
275
276				=item B<get_keys( )>
277
278				The list of keys specifying objects in the namespace associated
279				with this cache instance
280
281				=item B<get_identifiers( )>
282
283				This method has been deprecated in favor of B<get_keys( )>.
284
285				=item B<(get\|set)_auto_purge_interval( )>
286
287				Accesses the auto purge interval. If this option is set to a particular
288				time ( in the same format as the expires_in ), then the purge( )
289				routine will be called during the first get after the interval
290				expires. The interval will then be reset.
291
292				=item B<(get\|set)_auto_purge_on_set( )>
293
294				If this property is true, then the auto purge interval routine will be
295				checked on every set.
296
297				=item B<(get\|set)_auto_purge_on_get( )>
298
299				If this property is true, then the auto purge interval routine will be
300				checked on every get.
301
302				=back
303
304				=head1 SEE ALSO
305
306				Cache::Object, Cache::MemoryCache, Cache::FileCache,
307				Cache::SharedMemoryCache, and Cache::SizeAwareFileCache
308
309				=head1 AUTHOR
310
311				Original author: DeWitt Clinton <dewitt@unto.net>
312
313				Last author: $Author: dclinton $
314
315				Copyright (C) 2001-2003 DeWitt Clinton
316
317				=cut
318