1CHI(3) User Contributed Perl Documentation CHI(3)
2
6 CHI - Unified cache handling interface
7
9 version 0.44
10
12 use CHI;
13 # Choose a standard driver
15 #
16 my $cache = CHI->new( driver => 'Memory', global => 1 );
17 my $cache = CHI->new( driver => 'RawMemory', global => 1 );
18 my $cache = CHI->new( driver => 'File',
19 root_dir => '/path/to/root'
20 );
21 my $cache = CHI->new( driver => 'FastMmap',
22 root_dir => '/path/to/root',
23 cache_size => '1k'
24 );
25 my $cache = CHI->new( driver => 'Memcached::libmemcached',
26 servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
27 l1_cache => { driver => 'FastMmap', root_dir => '/path/to/root' }
28 );
29 my $cache = CHI->new( driver => 'DBI',
30 dbh => $dbh
31 );
32 my $cache = CHI->new( driver => 'BerkeleyDB',
33 root_dir => '/path/to/root'
34 );
35 # Create your own driver
37 #
38 my $cache = CHI->new( driver_class => 'My::Special::Driver', ... );
39 # Cache operations
41 #
42 my $customer = $cache->get($name);
43 if ( !defined $customer ) {
44 $customer = get_customer_from_db($name);
45 $cache->set( $name, $customer, "10 minutes" );
46 }
47 my $customer2 = $cache->compute($name2, "10 minutes", sub {
48 get_customer_from_db($name2)
49 });
50 $cache->remove($name);
51
53 CHI provides a unified caching API, designed to assist a developer in
54 persisting data for a specified period of time.
55 The CHI interface is implemented by driver classes that support
57 fetching, storing and clearing of data. Driver classes exist or will
58 exist for the gamut of storage backends available to Perl, such as
59 memory, plain files, memory mapped files, memcached, and DBI.
60 CHI is intended as an evolution of DeWitt Clinton's Cache::Cache
62 package, adhering to the basic Cache API but adding new features and
63 addressing limitations in the Cache::Cache implementation.
64
66 · Easy to create new drivers
67 · Uniform support for namespaces
69 · Automatic serialization of keys and values
71 · Multilevel caches
73 · Probabilistic expiration and busy locks, to reduce cache miss
75 stampedes
76 · Optional logging and statistics collection of cache activity
78
80 To create a new cache handle, call CHI->new. It takes the following
81 common options. All are optional, except that either driver or
82 driver_class must be passed.
83 compress_threshold [INT]
85 A value in bytes. Automatically compress values larger than this
86 before storing. Requires Compress::Zlib to be installed. Defaults
87 to undef, meaning no automatic compression. Inspired by the
88 parameter of the same name in Cache::Memcached.
89 # Compress values larger than 1MB
91 compress_threshold => 1024*1024
92 driver [STRING]
94 The name of a standard driver to drive the cache, for example
95 "Memory" or "File". CHI will prefix the string with
96 "CHI::Driver::".
97 driver_class [STRING]
99 The exact CHI::Driver subclass to drive the cache, for example
100 "My::Memory::Driver".
101 expires_in [DURATION]
103 expires_at [INT]
104 expires_variance [FLOAT]
105 Provide default values for the corresponding "set" options.
106 key_digester [STRING|HASHREF|OBJECT]
108 Digest algorithm to use on keys longer than "max_key_length" - e.g.
109 "MD5", "SHA-1", or "SHA-256".
110 Can be a Digest object, or a string or hashref which will passed to
112 Digest->new(). You will need to ensure Digest is installed to use
113 these options.
114 Default is "MD5".
116 key_serializer [STRING|HASHREF|OBJECT]
118 An object to use for serializing keys that are references. See
119 "serializer" above for the different ways this can be passed in.
120 The default is to use JSON in canonical mode (sorted hash keys).
121 label [STRING]
123 A label for the cache as a whole, independent of namespace - e.g.
124 "web-file-cache". Used when referring to the cache in logs,
125 statistics, and error messages. By default, set to
126 "short_driver_name".
127 l1_cache [HASHREF]
129 Add an L1 cache as a subcache. See "SUBCACHES".
130 max_key_length [INT]
132 Keys over this size will be digested. The default is driver-
133 specific; CHI::Driver::File, for example, defaults this to 240 due
134 to file system limits. For most drivers there is no maximum.
135 mirror_cache [HASHREF]
137 Add an mirror cache as a subcache. See "SUBCACHES".
138 namespace [STRING]
140 Identifies a namespace that all cache entries for this object will
141 be in. This allows easy separation of multiple, distinct caches
142 without worrying about key collision.
143 Suggestions for easy namespace selection:
145 · In a class, use the class name:
147 my $cache = CHI->new(namespace => __PACKAGE__, ...);
149 · In a script, use the script's absolute path name:
151 use Cwd qw(realpath);
153 my $cache = CHI->new(namespace => realpath($0), ...);
154 · In a web template, use the template name. For example, in
156 Mason, $m->cache will set the namespace to the current
157 component path.
158 Defaults to 'Default' if not specified.
160 on_get_error [STRING|CODEREF]
162 on_set_error [STRING|CODEREF]
163 How to handle runtime errors occurring during cache gets and cache
164 sets, which may or may not be considered fatal in your application.
165 Options are:
166 · log (the default) - log an error, or ignore if no logger is set
168 - see "LOGGING"
169 · ignore - do nothing
171 · warn - call warn() with an appropriate message
173 · die - call die() with an appropriate message
175 · coderef - call this code reference with three arguments: an
177 appropriate message, the key, and the original raw error
178 message
179 serializer [STRING|HASHREF|OBJECT]
181 An object to use for serializing data before storing it in the
182 cache, and deserializing data after retrieving it from the cache.
183 If this is a string, a Data::Serializer object will be created,
185 with the string passed as the 'serializer' option and raw=1. Common
186 options include 'Storable', 'Data::Dumper', and 'YAML'. If this is
187 a hashref, Data::Serializer will be called with the hash. You will
188 need to ensure Data::Serializer is installed to use these options.
189 Otherwise, this must be a Data::Serializer object or another object
191 that implements serialize() and deserialize().
192 e.g.
194 # Serialize using raw Data::Dumper
196 my $cache = CHI->new(serializer => 'Data::Dumper');
197 # Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex-encoded
199 my $cache = CHI->new(serializer => { serializer => 'Data::Dumper', compress => 1 });
200 # Serialize using custom object
202 my $cache = CHI->new(serializer => My::Custom::Serializer->new())
203 The default is to use raw Storable.
205 Some drivers will take additional constructor options. For example, the
207 File driver takes "root_dir" and "depth" options.
208
210 The following methods can be called on any cache handle returned from
211 CHI->new(). They are implemented in the CHI::Driver package.
212 Getting and setting
214 get( $key, [option => value, ...] )
215 Returns the data associated with $key. If $key does not exist or
216 has expired, returns undef. Expired items are not automatically
217 removed and may be examined with "get_object" or "get_expires_at".
218 $key may be followed by one or more name/value parameters:
220 expire_if [CODEREF]
222 If $key exists and has not expired, call code reference with
223 the CHI::CacheObject as a single parameter. If code returns a
224 true value, "get" returns undef as if the item were expired.
225 For example, to treat the cache as expired if $file has changed
226 since the value was computed:
227 $cache->get('foo', expire_if => sub { $_[0]->created_at < (stat($file))[9] });
229 busy_lock [DURATION]
231 If the value has expired, set its expiration time to the
232 current time plus the specified duration before returning
233 undef. This is used to prevent multiple processes from
234 recomputing the same expensive value simultaneously. The
235 problem with this technique is that it doubles the number of
236 writes performed - see "expires_variance" for another
237 technique.
238 set( $key, $data, [$expires_in | "now" | "never" | options] )
240 Associates $data with $key in the cache, overwriting any existing
241 entry. Returns $data.
242 The third argument to "set" is optional, and may be either a scalar
244 or a hash reference. If it is a scalar, it may be the string "now",
245 the string "never", or else a duration treated as an expires_in
246 value described below. If it is a hash reference, it may contain
247 one or more of the following options. Most of these options can be
248 provided with defaults in the cache constructor.
249 expires_in [DURATION]
251 Amount of time (in seconds) until this data expires.
252 expires_at [INT]
254 The epoch time at which the data expires.
255 expires_variance [FLOAT]
257 Controls the variable expiration feature, which allows items to
258 expire a little earlier than the stated expiration time to help
259 prevent cache miss stampedes.
260 Value is between 0.0 and 1.0, with 0.0 meaning that items
262 expire exactly when specified (feature is disabled), and 1.0
263 meaning that items might expire anytime from now til the stated
264 expiration time. The default is 0.0. A setting of 0.10 to 0.25
265 would introduce a small amount of variation without interfering
266 too much with intended expiration times.
267 The probability of expiration increases as a function of how
269 far along we are in the potential expiration window, with the
270 probability being near 0 at the beginning of the window and
271 approaching 1 at the end.
272 For example, in all of the following cases, an item might be
274 considered expired any time between 15 and 20 minutes, with
275 about a 20% chance at 16 minutes, a 40% chance at 17 minutes,
276 and a 100% chance at 20 minutes.
277 my $cache = CHI->new ( ..., expires_variance => 0.25, ... );
279 $cache->set($key, $value, '20 min');
280 $cache->set($key, $value, { expires_at => time() + 20*60 });
281 my $cache = CHI->new ( ... );
283 $cache->set($key, $value, { expires_in => '20 min', expires_variance => 0.25 });
284 CHI will make a new probabilistic choice every time it needs to
286 know whether an item has expired (i.e. it does not save the
287 results of its determination), so you can get situations like
288 this:
289 my $value = $cache->get($key); # returns undef (indicating expired)
291 my $value = $cache->get($key); # returns valid value this time!
292 if ($cache->is_valid($key)) # returns undef (indicating expired)
294 if ($cache->is_valid($key)) # returns true this time!
295 Typical applications won't be affected by this, since the
297 object is recomputed as soon as it is determined to be expired.
298 But it's something to be aware of.
299 compute( $key, $set_options, $code )
301 Combines the "get" and "set" operations in a single call. Attempts
302 to get $key; if successful, returns the value. Otherwise, calls
303 $code and uses the return value as the new value for $key, which is
304 then returned. $set_options is a scalar or hash reference, used as
305 the third argument to set.
306 $cache->compute($key, '5min', sub {
308 # compute and return value for $key here
309 });
310 This method will eventually support the ability to recompute a
312 value in the background just before it actually expires, so that
313 users are not impacted by recompute time.
314 Note: Prior to version 0.40, the last two arguments were in reverse
316 order; both will be accepted for backward compatibility. We think
317 the coderef looks better at the end.
318 Removing and expiring
320 remove( $key )
321 Remove the data associated with the $key from the cache.
322 expire( $key )
324 If $key exists, expire it by setting its expiration time into the
325 past. Does not necessarily remove the data. Since this involves
326 essentially setting the value again, "remove" may be more efficient
327 for some drivers.
328 Inspecting keys
330 is_valid( $key )
331 Returns a boolean indicating whether $key exists in the cache and
332 has not expired. Note: Expiration may be determined
333 probabilistically if "expires_variance" was used.
334 exists_and_is_expired( $key )
336 Returns a boolean indicating whether $key exists in the cache and
337 has expired. Note: Expiration may be determined probabilistically
338 if "expires_variance" was used.
339 get_expires_at( $key )
341 Returns the epoch time at which $key definitively expires. Returns
342 undef if the key does not exist or it has no expiration time.
343 get_object( $key )
345 Returns a CHI::CacheObject object containing data about the entry
346 associated with $key, or undef if no such key exists. The object
347 will be returned even if the entry has expired, as long as it has
348 not been removed.
349 Namespace operations
351 clear( )
352 Remove all entries from the namespace.
353 get_keys( )
355 Returns a list of keys in the namespace. This may or may not
356 include expired keys, depending on the driver.
357 The keys may not look the same as they did when passed into "set";
359 they may have been serialized, utf8 encoded, and/or digested (see
360 "KEY AND VALUE TRANSFORMATIONS"). However, they may still be passed
361 back into "get", "set", etc. to access the same underlying objects.
362 i.e. the following code is guaranteed to produce all key/value
363 pairs from the cache:
364 map { ($_, $c->get($_)) } $c->get_keys()
366 purge( )
368 Remove all entries that have expired from the namespace associated
369 with this cache instance. Warning: May be very inefficient,
370 depending on the number of keys and the driver.
371 get_namespaces( )
373 Returns a list of namespaces associated with the cache. This may or
374 may not include empty namespaces, depending on the driver.
375 Multiple key/value operations
377 The methods in this section process multiple keys and/or values at
378 once. By default these are implemented with the obvious map operations,
379 but some cache drivers (e.g. Cache::Memcached) can override them with
380 more efficient implementations.
381 get_multi_arrayref( $keys )
383 Get the keys in list reference $keys, and return a list reference
384 of the same length with corresponding values or undefs.
385 get_multi_hashref( $keys )
387 Like "get_multi_arrayref", but returns a hash reference with each
388 key in $keys mapping to its corresponding value or undef. Will only
389 work with scalar keys.
390 set_multi( $key_values, $set_options )
392 Set the multiple keys and values provided in hash reference
393 $key_values. $set_options is a scalar or hash reference, used as
394 the third argument to set. Will only work with scalar keys.
395 remove_multi( $keys )
397 Removes the keys in list reference $keys.
398 dump_as_hash( )
400 Returns a hash reference containing all the non-expired keys and
401 values in the cache.
402 Property accessors
404 driver_class( )
405 Returns the full name of the driver class. e.g.
406 CHI->new(driver=>'File')->driver_class
408 => CHI::Driver::File
409 CHI->new(driver_class=>'CHI::Driver::File')->driver_class
410 => CHI::Driver::File
411 CHI->new(driver_class=>'My::Driver::File')->driver_class
412 => My::Driver::File
413 You should use this rather than "ref()". Due to some subclassing
415 tricks CHI employs, the actual class of the object is neither
416 guaranteed nor likely to be the driver class.
417 short_driver_name( )
419 Returns the name of the driver class, minus the CHI::Driver::
420 prefix, if any. e.g.
421 CHI->new(driver=>'File')->short_driver_name
423 => File
424 CHI->new(driver_class=>'CHI::Driver::File')->short_driver_name
425 => File
426 CHI->new(driver_class=>'My::Driver::File')->short_driver_name
427 => My::Driver::File
428 Standard read-write accessors
430 expires_in
431 expires_at
432 expires_variance
433 label
434 on_get_error
435 on_set_error
436 Standard read-only accessors
438 namespace
439 serializer
440 Deprecated methods
442 The following methods are deprecated and will be removed in a later
443 version:
444 is_empty
446
448 Duration expressions, which appear in the "set" command and various
449 other parts of the API, are parsed by Time::Duration::Parse. A
450 duration is either a plain number, which is treated like a number of
451 seconds, or a number and a string representing time units where the
452 string is one of:
453 s second seconds sec secs
455 m minute minutes min mins
456 h hr hour hours
457 d day days
458 w week weeks
459 M month months
460 y year years
461 e.g. the following are all valid duration expressions:
463 25
465 3s
466 5 seconds
467 1 minute and ten seconds
468 1 hour
469
471 CHI strives to accept arbitrary keys and values for caching regardless
472 of the limitations of the underlying driver.
473 Key transformations
475 · Keys that are references are serialized - see "key_serializer".
476 · Keys with wide (>255) characters are utf8 encoded.
478 · Keys exceeding the maximum length for the underlying driver are
480 digested - see "max_key_length" and "key_digester".
481 · For some drivers (e.g. CHI::Driver::File), keys containing special
483 characters or whitespace are escaped with URL-like escaping.
484 Note: All transformations above with the exception of escaping are one-
486 way, meaning that CHI does not attempt to undo them when returned from
487 "get_keys"; and idempotent, meaning that applying them a second time
488 has no effect. So when you call "get_keys", the key you get may not be
489 exactly what you passed in, but you'll be able to pass that key in to
490 get the corresponding object.
491 Value transformations
493 · Values which are references are automatically serialized before
494 storing, and deserialized after retrieving - see "serializer".
495 · Values with their utf8 flag on are utf8 encoded before storing, and
497 utf8 decoded after retrieving.
498
500 It is possible to a cache to have one or more subcaches. There are
501 currently two types of subcaches: L1 and mirror.
502 L1 cache
504 An L1 (or "level one") cache sits in front of the primary cache,
505 usually to provide faster access for commonly accessed cache entries.
506 For example, this places an in-process Memory cache in front of a
507 Memcached cache:
508 my $cache = CHI->new(
510 driver => 'Memcached',
511 servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
512 l1_cache => { driver => 'Memory' }
513 );
514 On a "get", the L1 cache is checked first - if a valid value exists, it
516 is returned. Otherwise, the primary cache is checked - if a valid value
517 exists, it is returned, and the value is placed in the L1 cache with
518 the same expiration time. In this way, items fetched most frequently
519 from the primary cache will tend to be in the L1 cache.
520 "set" operations are distributed to both the primary and L1 cache.
522 You can access the L1 cache with the "l1_cache" method. For example,
524 this clears the L1 cache but leaves the primary cache intact:
525 $cache->l1_cache->clear();
527 Mirror cache
529 A mirror cache is a write-only cache that, over time, mirrors the
530 content of the primary cache. "set" operations are distributed to both
531 the primary and mirror cache, but "get" operations go only to the
532 primary cache.
533 Mirror caches are useful when you want to migrate from one cache to
535 another. You can populate a mirror cache and switch over to it once it
536 is sufficiently populated. For example, here we migrate from an old to
537 a new cache directory:
538 my $cache = CHI->new(
540 driver => 'File',
541 root_dir => '/old/cache/root',
542 mirror_cache => { driver => 'File', root_dir => '/new/cache/root' },
543 );
544 We leave this running for a few hours (or as needed), then replace it
546 with
547 my $cache = CHI->new(
549 driver => 'File',
550 root_dir => '/new/cache/root'
551 );
552 You can access the mirror cache with the "mirror_cache" method. For
554 example, to see how many keys have made it over to the mirror cache:
555 my @keys = $cache->mirror_cache->get_keys();
557 Creating subcaches
559 As illustrated above, you create subcaches by passing the "l1_cache"
560 and/or "mirror_cache" option to the CHI constructor. These options, in
561 turn, should contain a hash of options to create the subcache with.
562 The cache containing the subcache is called the parent cache.
564 The following options are automatically inherited by the subcache from
566 the parent cache, and may not be overriden:
567 expires_at
569 expires_in
570 expires_variance
571 serializer
572 (Reason: for efficiency, we want to create a single cache object and
574 store it in both caches. The cache object contains expiration
575 information and is dependent on the serializer. At some point we could
576 conceivably add code that will use a single object or separate objects
577 as necessary, and thus allow the above to be overriden.)
578 The following options are automatically inherited by the subcache from
580 the parent cache, but may be overriden:
581 namespace
583 on_get_error
584 on_set_error
585 All other options are initialized in the subcache as normal,
587 irrespective of their values in the parent.
588 It is not currently possible to pass an existing cache in as a
590 subcache.
591 Common subcache behaviors
593 These behaviors hold regardless of the type of subcache.
594 The following methods are distributed to both the primary cache and
596 subcache:
597 clear
599 expire
600 purge
601 remove
602 The following methods return information solely from the primary cache.
604 However, you are free to call them explicitly on the subcache. (Trying
605 to merge in subcache information automatically would require too much
606 guessing about the caller's intent.)
607 get_keys
609 get_namespaces
610 get_object
611 get_expires_at
612 exists_and_is_expired
613 is_valid
614 dump_as_hash
615 Multiple subcaches
617 It is valid for a cache to have one of each kind of subcache, e.g. an
618 L1 cache and a mirror cache.
619 A cache cannot have more than one of each kind of subcache, but a
621 subcache can have its own subcaches, and so on. e.g.
622 my $cache = CHI->new(
624 driver => 'Memcached',
625 servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
626 l1_cache => {
627 driver => 'File',
628 root_dir => '/path/to/root',
629 l1_cache => { driver => 'RawMemory' }
630 }
631 );
632 Methods for parent caches
634 has_subcaches( )
635 Returns a boolean indicating whether this cache has subcaches.
636 l1_cache( )
638 Returns the L1 cache for this cache, if any. Can only be called if
639 has_subcaches is true.
640 mirror_cache( )
642 Returns the mirror cache for this cache, if any. Can only be called
643 if has_subcaches is true.
644 subcaches( )
646 Returns the subcaches for this cache, in arbitrary order. Can only
647 be called if has_subcaches is true.
648 Methods for subcaches
650 is_subcache( )
651 Returns a boolean indicating whether this is a subcache.
652 subcache_type( )
654 Returns the type of subcache as a string, e.g. 'l1_cache' or
655 'mirror_cache'. Can only be called if is_subcache is true.
656 parent_cache( )
658 Returns the parent cache (weakened to prevent circular reference).
659 Can only be called if is_subcache is true.
660 Developing new kinds of subcaches
662 At this time, subcache behavior is hardcoded into CHI::Driver, so there
663 is no easy way to modify the behavior of existing subcache types or
664 create new ones. We'd like to make this more flexible eventually.
665
667 If "is_size_aware" or "max_size" are passed to the constructor, the
668 cache will be size aware - that is, it will keep track of its own size
669 (in bytes) as items are added and removed. You can get a cache's size
670 with "get_size".
671 Size aware caches generally keep track of their size in a separate
673 meta-key, and have to do an extra store whenever the size changes (e.g.
674 on each set and remove).
675 Maximum size and discard policies
677 If a cache's size rises above its "max_size", items are discarded until
678 the cache size is sufficiently below the max size. (See
679 "max_size_reduction_factor" for how to fine-tune this.)
680 The order in which items are discarded is controlled with
682 "discard_policy". The default discard policy is 'arbitrary', which
683 discards items in an arbitrary order. The available policies and
684 default policy can differ with each driver, e.g. the
685 CHI::Driver::Memory driver provides and defaults to an 'LRU' policy.
686 Appropriate drivers
688 Size awareness was chiefly designed for, and works well with, the
689 CHI::Driver::Memory driver: one often needs to enforce a maximum size
690 on a memory cache, and the overhead of tracking size in memory is
691 negligible. However, the capability may be useful with other drivers.
692 Some drivers - for example, CHI::Driver::FastMmap and
694 CHI::Driver::Memcached - inherently keep track of their size and
695 enforce a maximum size, and it makes no sense to turn on CHI's size
696 awareness for these.
697 Also, for drivers that cannot atomically read and update a value - for
699 example, CHI::Driver::File - there is a race condition in the updating
700 of size that can cause the size to grow inaccurate over time.
701
703 The following drivers are currently available as part of this
704 distribution:
705 · CHI::Driver::Memory - In-process memory based cache
707 · CHI::Driver::RawMemory - In-process memory based cache that stores
709 references directly instead of deep-copying
710 · CHI::Driver::File - File-based cache using one file per entry in a
712 multi-level directory structure
713 · CHI::Driver::FastMmap - Shared memory interprocess cache via
715 mmap'ed files
716 · CHI::Driver::Null - Dummy cache in which nothing is stored
718 · CHI::Driver::CacheCache - CHI wrapper for Cache::Cache
720 The following drivers are currently available as separate CPAN
722 distributions:
723 · CHI::Driver::Memcached - Distributed memory-based cache (works with
725 Cache::Memcached, Cache::Memcached::Fast, and
726 Cache::Memcached::libmemcached)
727 · CHI::Driver::DBI - Cache in any DBI-supported database
729 · CHI::Driver::BerkeleyDB - Cache in BerkeleyDB files
731 · CHI::Driver::Redis - Cache in Redis <http://redis.io/>
733 This list is likely incomplete. A complete set of drivers can be found
735 on CPAN by searching for "CHI::Driver".
736
738 See CHI::Benchmarks for a comparison of read/write times of both CHI
739 and non-CHI cache implementations.
740 "etc/bench/bench.pl" in the "CHI" distribution contains a script to run
742 these types of benchmarks on your own system.
743
745 See CHI::Driver::Development for information on developing new drivers.
746
748 "CHI" uses Log::Any for logging events. For example, a debug log
749 message is sent for every cache get and set.
750 See Log::Any documentation for how to control where logs get sent, if
752 anywhere.
753
755 CHI can record statistics, such as number of hits, misses and sets, on
756 a per-namespace basis and log the results to your Log::Any logger. You
757 can then use utilities included with this distribution to read stats
758 back from the logs and report a summary. See CHI::Stats for details.
759
761 Cache::Cache
762 CHI is intended as an evolution of DeWitt Clinton's Cache::Cache
763 package. It starts with the same basic API (which has proven durable
764 over time) but addresses some implementation shortcomings that cannot
765 be fixed in Cache::Cache due to backward compatibility concerns. In
766 particular:
767 Performance
769 Some of Cache::Cache's subclasses (e.g. Cache::FileCache) have been
770 justifiably criticized as inefficient. CHI has been designed from
771 the ground up with performance in mind, both in terms of general
772 overhead and in the built-in driver classes. Method calls are kept
773 to a minimum, data is only serialized when necessary, and metadata
774 such as expiration time is stored in packed binary format alongside
775 the data.
776 As an example, using Rob Mueller's cacheperl benchmarks, CHI's file
778 driver runs 3 to 4 times faster than Cache::FileCache.
779 Ease of subclassing
781 New Cache::Cache subclasses can be tedious to create, due to a lack
782 of code refactoring, the use of non-OO package subroutines, and the
783 separation of "cache" and "backend" classes. With CHI, the goal is
784 to make the creation of new drivers as easy as possible, roughly
785 the same as writing a TIE interface to your data store. Concerns
786 like serialization and expiration options are handled by the driver
787 base class so that individual drivers don't have to worry about
788 them.
789 Increased compatibility with cache implementations
791 Probably because of the reasons above, Cache::Cache subclasses were
792 never created for some of the most popular caches available on
793 CPAN, e.g. Cache::FastMmap and Cache::Memcached. CHI's goal is to
794 be able to support these and other caches with a minimum
795 performance overhead and minimum of glue code required.
796 Cache
798 The Cache distribution is another redesign and implementation of Cache,
799 created by Chris Leishman in 2003. Like CHI, it improves performance
800 and reduces the barrier to implementing new cache drivers. It breaks
801 with the Cache::Cache interface in a few ways that I considered non-
802 negotiable - for example, get/set do not serialize data, and namespaces
803 are an optional feature that drivers may decide not to implement.
804 Cache::Memcached, Cache::FastMmap, etc.
806 CPAN sports a variety of full-featured standalone cache modules
807 representing particular backends. CHI does not reinvent these but
808 simply wraps them with an appropriate driver. For example,
809 CHI::Driver::Memcached and CHI::Driver::FastMmap are thin layers around
810 Cache::Memcached and Cache::FastMmap.
811 Of course, because these modules already work on their own, there will
813 be some overlap. Cache::FastMmap, for example, already has code to
814 serialize data and handle expiration times. Here's how CHI resolves
815 these overlaps.
816 Serialization
818 CHI handles its own serialization, passing a flat binary string to
819 the underlying cache backend.
820 Expiration
822 CHI packs expiration times (as well as other metadata) inside the
823 binary string passed to the underlying cache backend. The backend
824 is unaware of these values; from its point of view the item has no
825 expiration time. Among other things, this means that you can use
826 CHI to examine expired items (e.g. with $cache->get_object) even if
827 this is not supported natively by the backend.
828 At some point CHI will provide the option of explicitly notifying
830 the backend of the expiration time as well. This might allow the
831 backend to do better storage management, etc., but would prevent
832 CHI from examining expired items.
833 Naturally, using CHI's FastMmap or Memcached driver will never be as
835 time or storage efficient as simply using Cache::FastMmap or
836 Cache::Memcached. In terms of performance, we've attempted to make the
837 overhead as small as possible, on the order of 5% per get or set
838 (benchmarks coming soon). In terms of storage size, CHI adds about 16
839 bytes of metadata overhead to each item. How much this matters
840 obviously depends on the typical size of items in your cache.
841
843 Questions and feedback are welcome, and should be directed to the perl-
844 cache mailing list:
845 http://groups.google.com/group/perl-cache-discuss
847 Bugs and feature requests will be tracked at RT:
849 http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI
851 bug-chi@rt.cpan.org
852 The latest source code can be browsed and fetched at:
854 http://github.com/jonswar/perl-chi/tree/master
856 git clone git://github.com/jonswar/perl-chi.git
857
859 · Perform cache benchmarks comparing both CHI and non-CHI cache
860 implementations
861 · Release BerkeleyDB drivers as separate CPAN distributions
863 · Add docs comparing various strategies for reducing miss stampedes
865 and cost of recomputes
866 · Add expires_next syntax (e.g. expires_next => 'hour')
868 · Support automatic serialization and escaping of keys
870 · Create XS versions of main functions in Driver.pm (e.g. get, set)
872
874 Thanks to Dewitt Clinton for the original Cache::Cache, to Rob Mueller
875 for the Perl cache benchmarks, and to Perrin Harkins for the
876 discussions that got this going.
877 CHI was originally designed and developed for the Digital Media group
879 of the Hearst Corporation, a diversified media company based in New
880 York City. Many thanks to Hearst management for agreeing to this open
881 source release.
882
884 Cache::Cache
885
887 Jonathan Swartz <swartz@pobox.com>
888
890 This software is copyright (c) 2011 by Jonathan Swartz.
891 This is free software; you can redistribute it and/or modify it under
893 the same terms as the Perl 5 programming language system itself.
894perl v5.12.3 2011-03-17 CHI(3)