1CHI(3) User Contributed Perl Documentation CHI(3)
2
6 CHI - Unified cache handling interface
7
9 version 0.60
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 => '+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 object, call "<CHI->new". It takes the common
81 options listed below. driver is required; all others are optional.
82 Some drivers will take additional constructor options. For example, the
84 File driver takes "root_dir" and "depth" options.
85 You can configure default options for each new cache object created -
87 see "SUBCLASSING AND CONFIGURING CHI".
88 Note that "CHI->new" returns an instance of a subclass of CHI::Driver,
90 not "CHI".
91 compress_threshold [INT]
93 A value in bytes. Automatically compress values larger than this
94 before storing. Requires Compress::Zlib to be installed. Defaults
95 to undef, meaning no automatic compression. Inspired by the
96 parameter of the same name in Cache::Memcached.
97 # Compress values larger than 1MB
99 compress_threshold => 1024*1024
100 driver [STRING]
102 Required. The name of a cache driver, for example "Memory" or
103 "File". CHI will prefix the string with "CHI::Driver::", unless it
104 begins with '+'. e.g.
105 driver => 'File'; # uses CHI::Driver::File
107 driver => '+My::CHI::Driver::File' # uses My::CHI::Driver::File
108 expires_in [DURATION], expires_at [INT], expires_variance [FLOAT]
110 Provide default values for the corresponding "set" options.
111 expires_on_backend [NUM]
113 If set to 0 (the default), CHI alone is aware of the expiration
114 time and does not pass it along to the backend driver. This allows
115 you to use "get_object" to retrieve expired items.
116 If set to 1, pass expiration times to backend driver if the driver
118 supports it -- for example, CHI::Driver::Memcached and
119 CHI::Driver::CacheCache. This may allow the driver to better manage
120 its space and evict items. Note that only simple expiration time
121 will be passed along, e.g. not "expires_variance".
122 If set to a number greater than 1 (e.g. 1.25), the time until
124 expiration will be multiplied by that number before being passed to
125 the backend driver. This gives you a customizable window of
126 opportunity to retrieve expired items.
127 key_digester [STRING|HASHREF|OBJECT]
129 Digest algorithm to use on keys longer than "max_key_length" - e.g.
130 "MD5", "SHA-1", or "SHA-256".
131 Can be a Digest object, or a string or hashref which will passed to
133 Digest->new(). You will need to ensure Digest is installed to use
134 these options.
135 Default is "MD5".
137 key_serializer [STRING|HASHREF|OBJECT]
139 An object to use for serializing keys that are references. See
140 "serializer" above for the different ways this can be passed in.
141 The default is to use the JSON backend in canonical mode (sorted
142 hash keys).
143 label [STRING]
145 A label for the cache as a whole, independent of namespace - e.g.
146 "web-file-cache". Used when referring to the cache in logs,
147 statistics, and error messages. By default, set to
148 "short_driver_name".
149 l1_cache [HASHREF]
151 Add an L1 cache as a subcache. See "SUBCACHES".
152 max_key_length [INT]
154 Keys over this size will be digested. The default is driver-
155 specific; CHI::Driver::File, for example, defaults this to 240 due
156 to file system limits. For most drivers there is no maximum.
157 mirror_cache [HASHREF]
159 Add an mirror cache as a subcache. See "SUBCACHES".
160 namespace [STRING]
162 Identifies a namespace that all cache entries for this object will
163 be in. This allows easy separation of multiple, distinct caches
164 without worrying about key collision.
165 Suggestions for easy namespace selection:
167 • In a class, use the class name:
169 my $cache = CHI->new(namespace => __PACKAGE__, ...);
171 • In a script, use the script's absolute path name:
173 use Cwd qw(realpath);
175 my $cache = CHI->new(namespace => realpath($0), ...);
176 • In a web template, use the template name. For example, in
178 Mason, $m->cache will set the namespace to the current
179 component path.
180 Defaults to 'Default' if not specified.
182 on_get_error [STRING|CODEREF]
184 on_set_error [STRING|CODEREF]
185 How to handle runtime errors occurring during cache gets and cache
186 sets, which may or may not be considered fatal in your application.
187 Options are:
188 • log (the default) - log an error, or ignore if no logger is set
190 - see "LOGGING"
191 • ignore - do nothing
193 • warn - call warn() with an appropriate message
195 • die - call die() with an appropriate message
197 • coderef - call this code reference with three arguments: an
199 appropriate message, the key, and the original raw error
200 message
201 serializer [STRING|HASHREF|OBJECT]
203 An object to use for serializing data before storing it in the
204 cache, and deserializing data after retrieving it from the cache.
205 Only references will be serialized; plain scalars will be placed in
206 the cache as-is.
207 If this is a string, a Data::Serializer object will be created,
209 with the string passed as the 'serializer' option and raw=1. Common
210 options include 'Storable', 'Data::Dumper', and 'YAML'. If this is
211 a hashref, Data::Serializer will be called with the hash. You will
212 need to ensure Data::Serializer is installed to use these options.
213 Otherwise, this must be a Data::Serializer object or another object
215 that implements serialize() and deserialize().
216 e.g.
218 # Serialize using raw Data::Dumper
220 my $cache = CHI->new(serializer => 'Data::Dumper');
221 # Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex-encoded
223 my $cache = CHI->new(serializer => { serializer => 'Data::Dumper', compress => 1 });
224 # Serialize using custom object
226 my $cache = CHI->new(serializer => My::Custom::Serializer->new())
227 The default is to use raw Storable.
229 traits [LISTREF]
231 List of one or more roles to apply to the "CHI::Driver" class that
232 is constructed. The roles will automatically be prefixed with
233 "CHI::Driver::Role::" unless preceded with a '+'. e.g.
234 traits => ['StoresAccessedAt', '+My::CHI::Driver::Role']
236
238 The following methods can be called on any cache handle returned from
239 CHI->new(). They are implemented in the CHI::Driver package.
240 Getting and setting
242 get( $key, [option => value, ...] )
243 Returns the data associated with $key. If $key does not exist or
244 has expired, returns undef. Expired items are not automatically
245 removed and may be examined with "get_object" or "get_expires_at".
246 $key may be followed by one or more name/value parameters:
248 expire_if [CODEREF]
250 If $key exists and has not expired, call code reference with
251 the CHI::CacheObject and CHI::Driver as the parameters. If code
252 returns a true value, "get" returns undef as if the item were
253 expired. For example, to treat the cache as expired if $file
254 has changed since the value was computed:
255 $cache->get('foo', expire_if => sub { $_[0]->created_at < (stat($file))[9] });
257 busy_lock [DURATION]
259 If the value has expired, the get will still return undef, but
260 the expiration time of the cache entry will be set to the
261 current time plus the specified duration. This is used to
262 prevent multiple processes from recomputing the same expensive
263 value simultaneously. The problem with this technique is that
264 it doubles the number of writes performed - see
265 "expires_variance" for another technique.
266 obj_ref [SCALARREF]
268 If the item exists in cache (even if expired), place the
269 CHI::CacheObject object in the provided SCALARREF.
270 set( $key, $data, [$expires_in | "now" | "never" | options] )
272 Associates $data with $key in the cache, overwriting any existing
273 entry. Returns $data.
274 The third argument to "set" is optional, and may be either a scalar
276 or a hash reference. If it is a scalar, it may be the string "now",
277 the string "never", or else a duration treated as an expires_in
278 value described below. If it is a hash reference, it may contain
279 one or more of the following options. Most of these options can be
280 provided with defaults in the cache constructor.
281 expires_in [DURATION]
283 Amount of time from now until this data expires. DURATION may
284 be an integer number of seconds or a duration expression.
285 expires_at [INT]
287 The epoch time at which the data expires.
288 expires_variance [FLOAT]
290 Controls the variable expiration feature, which allows items to
291 expire a little earlier than the stated expiration time to help
292 prevent cache miss stampedes.
293 Value is between 0.0 and 1.0, with 0.0 meaning that items
295 expire exactly when specified (feature is disabled), and 1.0
296 meaning that items might expire anytime from now until the
297 stated expiration time. The default is 0.0. A setting of 0.10
298 to 0.25 would introduce a small amount of variation without
299 interfering too much with intended expiration times.
300 The probability of expiration increases as a function of how
302 far along we are in the potential expiration window, with the
303 probability being near 0 at the beginning of the window and
304 approaching 1 at the end.
305 For example, in all of the following cases, an item might be
307 considered expired any time between 15 and 20 minutes, with
308 about a 20% chance at 16 minutes, a 40% chance at 17 minutes,
309 and a 100% chance at 20 minutes.
310 my $cache = CHI->new ( ..., expires_variance => 0.25, ... );
312 $cache->set($key, $value, '20 min');
313 $cache->set($key, $value, { expires_at => time() + 20*60 });
314 my $cache = CHI->new ( ... );
316 $cache->set($key, $value, { expires_in => '20 min', expires_variance => 0.25 });
317 CHI will make a new probabilistic choice every time it needs to
319 know whether an item has expired (i.e. it does not save the
320 results of its determination), so you can get situations like
321 this:
322 my $value = $cache->get($key); # returns undef (indicating expired)
324 my $value = $cache->get($key); # returns valid value this time!
325 if ($cache->is_valid($key)) # returns undef (indicating expired)
327 if ($cache->is_valid($key)) # returns true this time!
328 Typical applications won't be affected by this, since the
330 object is recomputed as soon as it is determined to be expired.
331 But it's something to be aware of.
332 compute( $key, $options, $code )
334 Combines the "get" and "set" operations in a single call. Attempts
335 to get $key; if successful, returns the value. Otherwise, calls
336 $code and uses the return value as the new value for $key, which is
337 then returned. Caller context (scalar or list) is respected.
338 $options can be undef, a scalar, or a hash reference. If it is
340 undef, it has no effect. If it is a scalar, it is treated as the
341 "expires_in" duration and passed as the third argument to "set". If
342 it is a hash reference, it may contain name/value pairs for both
343 "get" and "set". e.g.
344 # No expiration
346 my $value = $cache->compute($key, undef, sub {
347 # compute and return value for $key here
348 });
349 # Expire in 5 minutes
351 my $value = $cache->compute($key, '5min', sub {
352 # compute and return value for $key here
353 });
354 # Expire in 5 minutes or when a particular condition occurs
356 my $value = $cache->compute($key,
357 { expires_in => '5min', expire_if => sub { ... } },
358 sub {
359 # compute and return value for $key here
360 });
361 # List context
363 my @value = $cache->compute($key, '5min', sub {
364 ...
365 return @some_list;
366 });
367 This method will eventually support the ability to recompute a
369 value in the background just before it actually expires, so that
370 users are not impacted by recompute time.
371 Note: Prior to version 0.40, the last two arguments were in reverse
373 order; both will be accepted for backward compatibility. We think
374 the coderef looks better at the end.
375 Removing and expiring
377 remove( $key )
378 Remove the data associated with the $key from the cache.
379 expire( $key )
381 If $key exists, expire it by setting its expiration time into the
382 past. Does not necessarily remove the data. Since this involves
383 essentially setting the value again, "remove" may be more efficient
384 for some drivers.
385 Inspecting keys
387 is_valid( $key )
388 Returns a boolean indicating whether $key exists in the cache and
389 has not expired. Note: Expiration may be determined
390 probabilistically if "expires_variance" was used.
391 exists_and_is_expired( $key )
393 Returns a boolean indicating whether $key exists in the cache and
394 has expired. Note: Expiration may be determined probabilistically
395 if "expires_variance" was used.
396 get_expires_at( $key )
398 Returns the epoch time at which $key definitively expires. Returns
399 undef if the key does not exist or it has no expiration time.
400 get_object( $key )
402 Returns a CHI::CacheObject object containing data about the entry
403 associated with $key, or undef if no such key exists. The object
404 will be returned even if the entry has expired, as long as it has
405 not been removed.
406 Atomic operations (ALPHA)
408 These methods combine both reading and writing of a cache entry in a
409 single operation. The names and behaviors were adapted from memcached
410 <http://memcached.org/>.
411 Some drivers (e.g. CHI::Driver::Memcached::libmemcached,
413 CHI::Driver::DBI) may implement these as truly atomic operations, and
414 will be documented thusly. The default implementations are not atomic:
415 the get and set occur discretely and another process could potentially
416 modify the cache in between them.
417 These operations are labeled ALPHA because we haven't yet figured out
419 how they integrate with other CHI features, in particular "SUBCACHES".
420 APIs and behavior may change.
421 add( $key, $data, [$expires_in | "now" | "never" | options] )
423 Do a set, but only if $key is not valid in the cache.
424 replace( $key, $data, [$expires_in | "now" | "never" | options] )
426 Do a set, but only if $key is valid in the cache.
427 append( $key, $new_data)
429 Append $new_data to whatever value is currently associated with
430 $key. Has no effect if $key does not exist in the cache.
431 Returns true if $key was in the cache, false otherwise.
433 This is intended for simple string values only. For efficiency's
435 sake, CHI won't attempt to check for, or handle, the case where
436 data is serialized or compressed; the new data will simply be
437 appended, and an error will most probably occur when you try to
438 retrieve the value.
439 Does not modify expiration or other metadata. If $key exists but is
441 expired, it will remain expired.
442 If you use a driver with the non-atomic (default) implementation,
444 some appends may be lost due to race conditions.
445 Namespace operations
447 clear( )
448 Remove all entries from the namespace.
449 get_keys( )
451 Returns a list of keys in the namespace. This may or may not
452 include expired keys, depending on the driver.
453 The keys may not look the same as they did when passed into "set";
455 they may have been serialized, utf8 encoded, and/or digested (see
456 "KEY AND VALUE TRANSFORMATIONS"). However, they may still be passed
457 back into "get", "set", etc. to access the same underlying objects.
458 i.e. the following code is guaranteed to produce all key/value
459 pairs from the cache:
460 map { ($_, $c->get($_)) } $c->get_keys()
462 purge( )
464 Remove all entries that have expired from the namespace associated
465 with this cache instance. Warning: May be very inefficient,
466 depending on the number of keys and the driver.
467 get_namespaces( )
469 Returns a list of namespaces associated with the cache. This may or
470 may not include empty namespaces, depending on the driver.
471 Multiple key/value operations
473 The methods in this section process multiple keys and/or values at
474 once. By default these are implemented with the obvious map operations,
475 but some cache drivers (e.g. Cache::Memcached) can override them with
476 more efficient implementations.
477 get_multi_arrayref( $keys )
479 Get the keys in list reference $keys, and return a list reference
480 of the same length with corresponding values or undefs.
481 get_multi_hashref( $keys )
483 Like "get_multi_arrayref", but returns a hash reference with each
484 key in $keys mapping to its corresponding value or undef. Will only
485 work with scalar keys.
486 set_multi( $key_values, $set_options )
488 Set the multiple keys and values provided in hash reference
489 $key_values. $set_options is a scalar or hash reference, used as
490 the third argument to set. Will only work with scalar keys.
491 remove_multi( $keys )
493 Removes the keys in list reference $keys.
494 dump_as_hash( )
496 Returns a hash reference containing all the non-expired keys and
497 values in the cache.
498 Property accessors
500 chi_root_class( )
501 Returns the name of the root class under which this object was
502 created, e.g. "CHI" or "My::CHI". See "SUBCLASSING AND CONFIGURING
503 CHI".
504 driver_class( )
506 Returns the full name of the driver class. e.g.
507 CHI->new(driver=>'File')->driver_class
509 => CHI::Driver::File
510 CHI->new(driver=>'+CHI::Driver::File')->driver_class
511 => CHI::Driver::File
512 CHI->new(driver=>'+My::Driver::File')->driver_class
513 => My::Driver::File
514 You should use this rather than "ref()". Due to some subclassing
516 tricks CHI employs, the actual class of the object is neither
517 guaranteed nor likely to be the driver class.
518 short_driver_name( )
520 Returns the name of the driver class, minus the CHI::Driver::
521 prefix, if any. e.g.
522 CHI->new(driver=>'File')->short_driver_name
524 => File
525 CHI->new(driver_class=>'CHI::Driver::File')->short_driver_name
526 => File
527 CHI->new(driver_class=>'My::Driver::File')->short_driver_name
528 => My::Driver::File
529 Standard read-write accessors
531 expires_in
532 expires_at
533 expires_variance
534 label
535 on_get_error
536 on_set_error
537 Standard read-only accessors
539 namespace
540 serializer
541 Deprecated methods
543 The following methods are deprecated and will be removed in a later
544 version:
545 is_empty
547
549 Duration expressions, which appear in the "set" command and various
550 other parts of the API, are parsed by Time::Duration::Parse. A
551 duration is either a plain number, which is treated like a number of
552 seconds, or a number and a string representing time units where the
553 string is one of:
554 s second seconds sec secs
556 m minute minutes min mins
557 h hr hour hours
558 d day days
559 w week weeks
560 M month months
561 y year years
562 e.g. the following are all valid duration expressions:
564 25
566 3s
567 5 seconds
568 1 minute and ten seconds
569 1 hour
570
572 CHI strives to accept arbitrary keys and values for caching regardless
573 of the limitations of the underlying driver.
574 Key transformations
576 • Keys that are references are serialized - see "key_serializer".
577 • Keys with wide (>255) characters are utf8 encoded.
579 • Keys exceeding the maximum length for the underlying driver are
581 digested - see "max_key_length" and "key_digester".
582 • For some drivers (e.g. CHI::Driver::File), keys containing special
584 characters or whitespace are escaped with URL-like escaping.
585 Note: All transformations above with the exception of escaping are one-
587 way, meaning that CHI does not attempt to undo them when returned from
588 "get_keys"; and idempotent, meaning that applying them a second time
589 has no effect. So when you call "get_keys", the key you get may not be
590 exactly what you passed in, but you'll be able to pass that key in to
591 get the corresponding object.
592 Value transformations
594 • Values which are references are automatically serialized before
595 storing, and deserialized after retrieving - see "serializer".
596 • Values with their utf8 flag on are utf8 encoded before storing, and
598 utf8 decoded after retrieving.
599
601 It is possible to a cache to have one or more subcaches. There are
602 currently two types of subcaches: L1 and mirror.
603 L1 cache
605 An L1 (or "level one") cache sits in front of the primary cache,
606 usually to provide faster access for commonly accessed cache entries.
607 For example, this places an in-process Memory cache in front of a
608 Memcached cache:
609 my $cache = CHI->new(
611 driver => 'Memcached',
612 servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
613 l1_cache => { driver => 'Memory', global => 1, max_size => 1024*1024 }
614 );
615 On a "get", the L1 cache is checked first - if a valid value exists, it
617 is returned. Otherwise, the primary cache is checked - if a valid value
618 exists, it is returned, and the value is placed in the L1 cache with
619 the same expiration time. In this way, items fetched most frequently
620 from the primary cache will tend to be in the L1 cache.
621 "set" operations are distributed to both the primary and L1 cache.
623 You can access the L1 cache with the "l1_cache" method. For example,
625 this clears the L1 cache but leaves the primary cache intact:
626 $cache->l1_cache->clear();
628 Mirror cache
630 A mirror cache is a write-only cache that, over time, mirrors the
631 content of the primary cache. "set" operations are distributed to both
632 the primary and mirror cache, but "get" operations go only to the
633 primary cache.
634 Mirror caches are useful when you want to migrate from one cache to
636 another. You can populate a mirror cache and switch over to it once it
637 is sufficiently populated. For example, here we migrate from an old to
638 a new cache directory:
639 my $cache = CHI->new(
641 driver => 'File',
642 root_dir => '/old/cache/root',
643 mirror_cache => { driver => 'File', root_dir => '/new/cache/root' },
644 );
645 We leave this running for a few hours (or as needed), then replace it
647 with
648 my $cache = CHI->new(
650 driver => 'File',
651 root_dir => '/new/cache/root'
652 );
653 You can access the mirror cache with the "mirror_cache" method. For
655 example, to see how many keys have made it over to the mirror cache:
656 my @keys = $cache->mirror_cache->get_keys();
658 Creating subcaches
660 As illustrated above, you create subcaches by passing the "l1_cache"
661 and/or "mirror_cache" option to the CHI constructor. These options, in
662 turn, should contain a hash of options to create the subcache with.
663 The cache containing the subcache is called the parent cache.
665 The following options are automatically inherited by the subcache from
667 the parent cache, and may not be overridden:
668 expires_at
670 expires_in
671 expires_variance
672 serializer
673 (Reason: for efficiency, we want to create a single cache object and
675 store it in both caches. The cache object contains expiration
676 information and is dependent on the serializer. At some point we could
677 conceivably add code that will use a single object or separate objects
678 as necessary, and thus allow the above to be overridden.)
679 The following options are automatically inherited by the subcache from
681 the parent cache, but may be overridden:
682 namespace
684 on_get_error
685 on_set_error
686 All other options are initialized in the subcache as normal,
688 irrespective of their values in the parent.
689 It is not currently possible to pass an existing cache in as a
691 subcache.
692 Common subcache behaviors
694 These behaviors hold regardless of the type of subcache.
695 The following methods are distributed to both the primary cache and
697 subcache:
698 clear
700 expire
701 purge
702 remove
703 The following methods return information solely from the primary cache.
705 However, you are free to call them explicitly on the subcache. (Trying
706 to merge in subcache information automatically would require too much
707 guessing about the caller's intent.)
708 get_keys
710 get_namespaces
711 get_object
712 get_expires_at
713 exists_and_is_expired
714 is_valid
715 dump_as_hash
716 Multiple subcaches
718 It is valid for a cache to have one of each kind of subcache, e.g. an
719 L1 cache and a mirror cache.
720 A cache cannot have more than one of each kind of subcache, but a
722 subcache can have its own subcaches, and so on. e.g.
723 my $cache = CHI->new(
725 driver => 'Memcached',
726 servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
727 l1_cache => {
728 driver => 'File',
729 root_dir => '/path/to/root',
730 l1_cache => { driver => 'RawMemory', global => 1 }
731 }
732 );
733 Methods for parent caches
735 has_subcaches( )
736 Returns a boolean indicating whether this cache has subcaches.
737 l1_cache( )
739 Returns the L1 cache for this cache, if any. Can only be called if
740 has_subcaches is true.
741 mirror_cache( )
743 Returns the mirror cache for this cache, if any. Can only be called
744 if has_subcaches is true.
745 subcaches( )
747 Returns the subcaches for this cache, in arbitrary order. Can only
748 be called if has_subcaches is true.
749 Methods for subcaches
751 is_subcache( )
752 Returns a boolean indicating whether this is a subcache.
753 subcache_type( )
755 Returns the type of subcache as a string, e.g. 'l1_cache' or
756 'mirror_cache'. Can only be called if is_subcache is true.
757 parent_cache( )
759 Returns the parent cache (weakened to prevent circular reference).
760 Can only be called if is_subcache is true.
761 Developing new kinds of subcaches
763 At this time, subcache behavior is hardcoded into CHI::Driver, so there
764 is no easy way to modify the behavior of existing subcache types or
765 create new ones. We'd like to make this more flexible eventually.
766
768 If "is_size_aware" or "max_size" are passed to the constructor, the
769 cache will be size aware - that is, it will keep track of its own size
770 (in bytes) as items are added and removed. You can get a cache's size
771 with "get_size".
772 Size aware caches generally keep track of their size in a separate
774 meta-key, and have to do an extra store whenever the size changes (e.g.
775 on each set and remove).
776 Maximum size and discard policies
778 If a cache's size rises above its "max_size", items are discarded until
779 the cache size is sufficiently below the max size. (See
780 "max_size_reduction_factor" for how to fine-tune this.)
781 The order in which items are discarded is controlled with
783 "discard_policy". The default discard policy is 'arbitrary', which
784 discards items in an arbitrary order. The available policies and
785 default policy can differ with each driver, e.g. the
786 CHI::Driver::Memory driver provides and defaults to an 'LRU' policy.
787 Appropriate drivers
789 Size awareness was chiefly designed for, and works well with, the
790 CHI::Driver::Memory driver: one often needs to enforce a maximum size
791 on a memory cache, and the overhead of tracking size in memory is
792 negligible. However, the capability may be useful with other drivers.
793 Some drivers - for example, CHI::Driver::FastMmap and
795 CHI::Driver::Memcached - inherently keep track of their size and
796 enforce a maximum size, and it makes no sense to turn on CHI's size
797 awareness for these.
798 Also, for drivers that cannot atomically read and update a value - for
800 example, CHI::Driver::File - there is a race condition in the updating
801 of size that can cause the size to grow inaccurate over time.
802
804 You can subclass CHI for your own application and configure it in a
805 variety of ways, e.g. predefining storage types and defaults for new
806 cache objects. Your configuration will be independent of the main CHI
807 class and other CHI subclasses.
808 Start with a trivial subclass:
810 package My::CHI;
812 use base qw(CHI);
814 1;
815 Then, just use your subclass in place of CHI:
817 my $cache = My::CHI->new( ... );
819 print $cache->chi_root_class;
821 ==> 'My::CHI'
822 This obviously doesn't change any behavior by itself. Here's an example
824 with actual config:
825 package My::CHI;
827 use base qw(CHI);
829 __PACKAGE__->config({
831 storage => {
832 local_file => { driver => 'File', root_dir => '/my/root' },
833 memcached => {
834 driver => 'Memcached::libmemcached',
835 servers => [ '10.0.0.15:11211', '10.0.0.15:11212' ]
836 },
837 },
838 namespace => {
839 'Foo' => { storage => 'local_file' },
840 'Bar' => { storage => 'local_file', depth => 3 },
841 'Baz' => { storage => 'memcached' },
842 }
843 defaults => { storage => 'local_file' },
844 memoize_cache_objects => 1,
845 });
846 1;
848 Each of these config keys is explained in the next section.
850 Configuration keys
852 storage
853 A map of names to parameter hashrefs. This provides a way to
854 encapsulate common sets of parameters that might be used in many
855 caches. e.g. if you define
856 storage => {
858 local_file => { driver => 'File', root_dir => '/my/root' },
859 ...
860 }
861 then
863 my $cache = My::CHI->new
865 (namespace => 'Foo', storage => 'local_file');
866 is equivalent to
868 my $cache = My::CHI->new
870 (namespace => 'Foo', driver => 'File', root_dir => '/my/root');
871 namespace
873 A map of namespace names to parameter hashrefs. When you create a
874 cache object with the specified namespace, the hashref of
875 parameters will be applied as defaults. e.g. if you define
876 namespace => {
878 'Foo' => { driver => 'File', root_dir => '/my/root' },
879 'Bar' => { storage => 'database' },
880 ...
881 }
882 then
884 my $cache1 = My::CHI->new
886 (namespace => 'Foo');
887 my $cache2 = My::CHI->new
888 (namespace => 'Bar');
889 is equivalent to
891 my $cache1 = My::CHI->new
893 (namespace => 'Foo', driver => 'File', root_dir => '/my/root');
894 my $cache2 = My::CHI->new
895 (namespace => 'Bar', storage => 'database');
896 defaults
898 A hash of parameters that will be used as core defaults for all
899 cache objects created under this root class. e.g.
900 defaults => {
902 on_get_error => 'die',
903 expires_variance => 0.2,
904 }
905 These can be overridden by namespace defaults, storage settings, or
907 "new" parameters.
908 memoize_cache_objects
910 True or false, indicates whether "My::CHI->new" should memoize and
911 return the same cache object if given the same parameters. This can
912 speed things up if you create cache objects frequently. Will
913 currently only work for 0- or 1- key parameter hashes. e.g.
914 My::CHI->config({
916 memoize_cache_objects => 1,
917 });
918 then
920 # $cache1 and $cache2 will be the same object, regardless of what
922 # namespace and storage defaults are associated with 'Foo'
923 #
924 my $cache1 = My::CHI->new(namespace => 'Foo');
925 my $cache2 = My::CHI->new(namespace => 'Foo');
926 # $cache3 and $cache4 will be different objects
928 #
929 my $cache3 = My::CHI->new
930 (namespace => 'Bar', driver => 'File', root_dir => '/my/root');
931 my $cache4 = My::CHI->new
932 (namespace => 'Bar', driver => 'File', root_dir => '/my/root');
933 To clear the memoized cache objects, call
935 My::CHI->clear_memoized_cache_objects;
937 How defaults are combined
939 Defaults are applied in the following order, from highest to lowest
940 precedence:
941 • Parameters passed in "new"
943 • Namespace defaults, if any
945 • Storage settings, if any
947 • Core defaults defined under 'defaults'
949 Inheritance of config
951 A subclass will automatically inherit the configuration of its parent
952 if it does not call "config" itself (ala Class::Data::Inheritable).
953 Reading config from a file
955 use YAML::XS qw(LoadFile);
956 __PACKAGE__->config(LoadFile("/path/to/cache.yml"));
958
960 The following drivers are currently available as part of this
961 distribution:
962 • CHI::Driver::Memory - In-process memory based cache
964 • CHI::Driver::RawMemory - In-process memory based cache that stores
966 references directly instead of serializing/deep-copying
967 • CHI::Driver::File - File-based cache using one file per entry in a
969 multi-level directory structure
970 • CHI::Driver::FastMmap - Shared memory interprocess cache via
972 mmap'ed files
973 • CHI::Driver::Null - Dummy cache in which nothing is stored
975 • CHI::Driver::CacheCache - CHI wrapper for Cache::Cache
977 The following drivers are currently available as separate CPAN
979 distributions:
980 • CHI::Driver::Memcached - Distributed memory-based cache (works with
982 Cache::Memcached, Cache::Memcached::Fast, and
983 Cache::Memcached::libmemcached)
984 • CHI::Driver::DBI - Cache in any DBI-supported database
986 • CHI::Driver::BerkeleyDB - Cache in BerkeleyDB files
988 • CHI::Driver::Redis - Cache in Redis <http://redis.io/>
990 • CHI::Driver::SharedMem - Cache in shared memory
992 This list is likely incomplete. A complete set of drivers can be found
994 on CPAN by searching for "CHI::Driver".
995
997 See CHI::Benchmarks for a comparison of read/write times of both CHI
998 and non-CHI cache implementations.
999 "etc/bench/bench.pl" in the "CHI" distribution contains a script to run
1001 these types of benchmarks on your own system.
1002
1004 See CHI::Driver::Development for information on developing new drivers.
1005
1007 "CHI" uses Log::Any for logging events. For example, a debug log
1008 message is sent with category "CHI::Driver" for every cache get and
1009 set.
1010 See Log::Any documentation for how to control where logs get sent, if
1012 anywhere.
1013
1015 CHI can record statistics, such as number of hits, misses and sets, on
1016 a per-namespace basis and log the results to your Log::Any logger. You
1017 can then use utilities included with this distribution to read stats
1018 back from the logs and report a summary. See CHI::Stats for details.
1019
1021 Cache::Cache
1022 CHI is intended as an evolution of DeWitt Clinton's Cache::Cache
1023 package. It starts with the same basic API (which has proven durable
1024 over time) but addresses some implementation shortcomings that cannot
1025 be fixed in Cache::Cache due to backward compatibility concerns. In
1026 particular:
1027 Performance
1029 Some of Cache::Cache's subclasses (e.g. Cache::FileCache) have been
1030 justifiably criticized as inefficient. CHI has been designed from
1031 the ground up with performance in mind, both in terms of general
1032 overhead and in the built-in driver classes. Method calls are kept
1033 to a minimum, data is only serialized when necessary, and metadata
1034 such as expiration time is stored in packed binary format alongside
1035 the data.
1036 Ease of subclassing
1038 New Cache::Cache subclasses can be tedious to create, due to a lack
1039 of code refactoring, the use of non-OO package subroutines, and the
1040 separation of "cache" and "backend" classes. With CHI, the goal is
1041 to make the creation of new drivers as easy as possible, roughly
1042 the same as writing a TIE interface to your data store. Concerns
1043 like serialization and expiration options are handled by the driver
1044 base class so that individual drivers don't have to worry about
1045 them.
1046 Increased compatibility with cache implementations
1048 Probably because of the reasons above, Cache::Cache subclasses were
1049 never created for some of the most popular caches available on
1050 CPAN, e.g. Cache::FastMmap and Cache::Memcached. CHI's goal is to
1051 be able to support these and other caches with a minimum
1052 performance overhead and minimum of glue code required.
1053 Cache
1055 The Cache distribution is another redesign and implementation of Cache,
1056 created by Chris Leishman in 2003. Like CHI, it improves performance
1057 and reduces the barrier to implementing new cache drivers. It breaks
1058 with the Cache::Cache interface in a few ways that I considered non-
1059 negotiable - for example, get/set do not serialize data, and namespaces
1060 are an optional feature that drivers may decide not to implement.
1061 Cache::Memcached, Cache::FastMmap, etc.
1063 CPAN sports a variety of full-featured standalone cache modules
1064 representing particular backends. CHI does not reinvent these but
1065 simply wraps them with an appropriate driver. For example,
1066 CHI::Driver::Memcached and CHI::Driver::FastMmap are thin layers around
1067 Cache::Memcached and Cache::FastMmap.
1068 Of course, because these modules already work on their own, there will
1070 be some overlap. Cache::FastMmap, for example, already has code to
1071 serialize data and handle expiration times. Here's how CHI resolves
1072 these overlaps.
1073 Serialization
1075 CHI handles its own serialization, passing a flat binary string to
1076 the underlying cache backend. The notable exception is
1077 CHI::Driver::RawMemory which does no serialization.
1078 Expiration
1080 CHI packs expiration times (as well as other metadata) inside the
1081 binary string passed to the underlying cache backend. The backend
1082 is unaware of these values; from its point of view the item has no
1083 expiration time. Among other things, this means that you can use
1084 CHI to examine expired items (e.g. with $cache->get_object) even if
1085 this is not supported natively by the backend.
1086 At some point CHI will provide the option of explicitly notifying
1088 the backend of the expiration time as well. This might allow the
1089 backend to do better storage management, etc., but would prevent
1090 CHI from examining expired items.
1091 Naturally, using CHI's FastMmap or Memcached driver will never be as
1093 time or storage efficient as simply using Cache::FastMmap or
1094 Cache::Memcached. In terms of performance, we've attempted to make the
1095 overhead as small as possible, on the order of 5% per get or set
1096 (benchmarks coming soon). In terms of storage size, CHI adds about 16
1097 bytes of metadata overhead to each item. How much this matters
1098 obviously depends on the typical size of items in your cache.
1099
1101 Questions and feedback are welcome, and should be directed to the perl-
1102 cache mailing list:
1103 http://groups.google.com/group/perl-cache-discuss
1105 Bugs and feature requests will be tracked at RT:
1107 http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI
1109 bug-chi@rt.cpan.org
1110 The latest source code can be browsed and fetched at:
1112 http://github.com/jonswar/perl-chi/tree/master
1114 git clone git://github.com/jonswar/perl-chi.git
1115
1117 Thanks to Dewitt Clinton for the original Cache::Cache, to Rob Mueller
1118 for the Perl cache benchmarks, and to Perrin Harkins for the
1119 discussions that got this going.
1120 CHI was originally designed and developed for the Digital Media group
1122 of the Hearst Corporation, a diversified media company based in New
1123 York City. Many thanks to Hearst management for agreeing to this open
1124 source release.
1125
1127 Cache::Cache
1128
1130 Jonathan Swartz <swartz@pobox.com>
1131
1133 This software is copyright (c) 2012 by Jonathan Swartz.
1134 This is free software; you can redistribute it and/or modify it under
1136 the same terms as the Perl 5 programming language system itself.
1137perl v5.32.1 2021-01-26 CHI(3)