1CHI(3) User Contributed Perl Documentation CHI(3)
2
6 CHI - Unified cache handling interface
7
9 version 0.61
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->new will be called with the hash. You
212 will need to ensure Data::Serializer is installed to use these
213 options.
214 Otherwise, this must be a Data::Serializer object or another object
216 that implements serialize() and deserialize().
217 e.g.
219 # Serialize using raw Data::Dumper
221 my $cache = CHI->new(serializer => 'Data::Dumper');
222 # Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex-encoded
224 my $cache = CHI->new(serializer => { serializer => 'Data::Dumper', compress => 1 });
225 # Serialize using custom object
227 my $cache = CHI->new(serializer => My::Custom::Serializer->new())
228 The default is to use raw Storable.
230 traits [LISTREF]
232 List of one or more roles to apply to the "CHI::Driver" class that
233 is constructed. The roles will automatically be prefixed with
234 "CHI::Driver::Role::" unless preceded with a '+'. e.g.
235 traits => ['StoresAccessedAt', '+My::CHI::Driver::Role']
237
239 The following methods can be called on any cache handle returned from
240 CHI->new(). They are implemented in the CHI::Driver package.
241 Getting and setting
243 get( $key, [option => value, ...] )
244 Returns the data associated with $key. If $key does not exist or
245 has expired, returns undef. Expired items are not automatically
246 removed and may be examined with "get_object" or "get_expires_at".
247 $key may be followed by one or more name/value parameters:
249 expire_if [CODEREF]
251 If $key exists and has not expired, call code reference with
252 the CHI::CacheObject and CHI::Driver as the parameters. If code
253 returns a true value, "get" returns undef as if the item were
254 expired. For example, to treat the cache as expired if $file
255 has changed since the value was computed:
256 $cache->get('foo', expire_if => sub { $_[0]->created_at < (stat($file))[9] });
258 busy_lock [DURATION]
260 If the value has expired, the get will still return undef, but
261 the expiration time of the cache entry will be set to the
262 current time plus the specified duration. This is used to
263 prevent multiple processes from recomputing the same expensive
264 value simultaneously. The problem with this technique is that
265 it doubles the number of writes performed - see
266 "expires_variance" for another technique.
267 obj_ref [SCALARREF]
269 If the item exists in cache (even if expired), place the
270 CHI::CacheObject object in the provided SCALARREF.
271 set( $key, $data, [$expires_in | "now" | "never" | options] )
273 Associates $data with $key in the cache, overwriting any existing
274 entry. Returns $data.
275 The third argument to "set" is optional, and may be either a scalar
277 or a hash reference. If it is a scalar, it may be the string "now",
278 the string "never", or else a duration treated as an expires_in
279 value described below. If it is a hash reference, it may contain
280 one or more of the following options. Most of these options can be
281 provided with defaults in the cache constructor.
282 expires_in [DURATION]
284 Amount of time from now until this data expires. DURATION may
285 be an integer number of seconds or a duration expression.
286 expires_at [INT]
288 The epoch time at which the data expires.
289 expires_variance [FLOAT]
291 Controls the variable expiration feature, which allows items to
292 expire a little earlier than the stated expiration time to help
293 prevent cache miss stampedes.
294 Value is between 0.0 and 1.0, with 0.0 meaning that items
296 expire exactly when specified (feature is disabled), and 1.0
297 meaning that items might expire anytime from now until the
298 stated expiration time. The default is 0.0. A setting of 0.10
299 to 0.25 would introduce a small amount of variation without
300 interfering too much with intended expiration times.
301 The probability of expiration increases as a function of how
303 far along we are in the potential expiration window, with the
304 probability being near 0 at the beginning of the window and
305 approaching 1 at the end.
306 For example, in all of the following cases, an item might be
308 considered expired any time between 15 and 20 minutes, with
309 about a 20% chance at 16 minutes, a 40% chance at 17 minutes,
310 and a 100% chance at 20 minutes.
311 my $cache = CHI->new ( ..., expires_variance => 0.25, ... );
313 $cache->set($key, $value, '20 min');
314 $cache->set($key, $value, { expires_at => time() + 20*60 });
315 my $cache = CHI->new ( ... );
317 $cache->set($key, $value, { expires_in => '20 min', expires_variance => 0.25 });
318 CHI will make a new probabilistic choice every time it needs to
320 know whether an item has expired (i.e. it does not save the
321 results of its determination), so you can get situations like
322 this:
323 my $value = $cache->get($key); # returns undef (indicating expired)
325 my $value = $cache->get($key); # returns valid value this time!
326 if ($cache->is_valid($key)) # returns undef (indicating expired)
328 if ($cache->is_valid($key)) # returns true this time!
329 Typical applications won't be affected by this, since the
331 object is recomputed as soon as it is determined to be expired.
332 But it's something to be aware of.
333 compute( $key, $options, $code )
335 Combines the "get" and "set" operations in a single call. Attempts
336 to get $key; if successful, returns the value. Otherwise, calls
337 $code and uses the return value as the new value for $key, which is
338 then returned. Caller context (scalar or list) is respected.
339 $options can be undef, a scalar, or a hash reference. If it is
341 undef, it has no effect. If it is a scalar, it is treated as the
342 "expires_in" duration and passed as the third argument to "set". If
343 it is a hash reference, it may contain name/value pairs for both
344 "get" and "set". e.g.
345 # No expiration
347 my $value = $cache->compute($key, undef, sub {
348 # compute and return value for $key here
349 });
350 # Expire in 5 minutes
352 my $value = $cache->compute($key, '5min', sub {
353 # compute and return value for $key here
354 });
355 # Expire in 5 minutes or when a particular condition occurs
357 my $value = $cache->compute($key,
358 { expires_in => '5min', expire_if => sub { ... } },
359 sub {
360 # compute and return value for $key here
361 });
362 # List context
364 my @value = $cache->compute($key, '5min', sub {
365 ...
366 return @some_list;
367 });
368 This method will eventually support the ability to recompute a
370 value in the background just before it actually expires, so that
371 users are not impacted by recompute time.
372 Note: Prior to version 0.40, the last two arguments were in reverse
374 order; both will be accepted for backward compatibility. We think
375 the coderef looks better at the end.
376 Removing and expiring
378 remove( $key )
379 Remove the data associated with the $key from the cache.
380 expire( $key )
382 If $key exists, expire it by setting its expiration time into the
383 past. Does not necessarily remove the data. Since this involves
384 essentially setting the value again, "remove" may be more efficient
385 for some drivers.
386 Inspecting keys
388 is_valid( $key )
389 Returns a boolean indicating whether $key exists in the cache and
390 has not expired. Note: Expiration may be determined
391 probabilistically if "expires_variance" was used.
392 exists_and_is_expired( $key )
394 Returns a boolean indicating whether $key exists in the cache and
395 has expired. Note: Expiration may be determined probabilistically
396 if "expires_variance" was used.
397 get_expires_at( $key )
399 Returns the epoch time at which $key definitively expires. Returns
400 undef if the key does not exist or it has no expiration time.
401 get_object( $key )
403 Returns a CHI::CacheObject object containing data about the entry
404 associated with $key, or undef if no such key exists. The object
405 will be returned even if the entry has expired, as long as it has
406 not been removed.
407 Atomic operations (ALPHA)
409 These methods combine both reading and writing of a cache entry in a
410 single operation. The names and behaviors were adapted from memcached
411 <http://memcached.org/>.
412 Some drivers (e.g. CHI::Driver::Memcached::libmemcached,
414 CHI::Driver::DBI) may implement these as truly atomic operations, and
415 will be documented thusly. The default implementations are not atomic:
416 the get and set occur discretely and another process could potentially
417 modify the cache in between them.
418 These operations are labeled ALPHA because we haven't yet figured out
420 how they integrate with other CHI features, in particular "SUBCACHES".
421 APIs and behavior may change.
422 add( $key, $data, [$expires_in | "now" | "never" | options] )
424 Do a set, but only if $key is not valid in the cache.
425 replace( $key, $data, [$expires_in | "now" | "never" | options] )
427 Do a set, but only if $key is valid in the cache.
428 append( $key, $new_data)
430 Append $new_data to whatever value is currently associated with
431 $key. Has no effect if $key does not exist in the cache.
432 Returns true if $key was in the cache, false otherwise.
434 This is intended for simple string values only. For efficiency's
436 sake, CHI won't attempt to check for, or handle, the case where
437 data is serialized or compressed; the new data will simply be
438 appended, and an error will most probably occur when you try to
439 retrieve the value.
440 Does not modify expiration or other metadata. If $key exists but is
442 expired, it will remain expired.
443 If you use a driver with the non-atomic (default) implementation,
445 some appends may be lost due to race conditions.
446 Namespace operations
448 clear( )
449 Remove all entries from the namespace.
450 get_keys( )
452 Returns a list of keys in the namespace. This may or may not
453 include expired keys, depending on the driver.
454 The keys may not look the same as they did when passed into "set";
456 they may have been serialized, utf8 encoded, and/or digested (see
457 "KEY AND VALUE TRANSFORMATIONS"). However, they may still be passed
458 back into "get", "set", etc. to access the same underlying objects.
459 i.e. the following code is guaranteed to produce all key/value
460 pairs from the cache:
461 map { ($_, $c->get($_)) } $c->get_keys()
463 purge( )
465 Remove all entries that have expired from the namespace associated
466 with this cache instance. Warning: May be very inefficient,
467 depending on the number of keys and the driver.
468 get_namespaces( )
470 Returns a list of namespaces associated with the cache. This may or
471 may not include empty namespaces, depending on the driver.
472 Multiple key/value operations
474 The methods in this section process multiple keys and/or values at
475 once. By default these are implemented with the obvious map operations,
476 but some cache drivers (e.g. Cache::Memcached) can override them with
477 more efficient implementations.
478 get_multi_arrayref( $keys )
480 Get the keys in list reference $keys, and return a list reference
481 of the same length with corresponding values or undefs.
482 get_multi_hashref( $keys )
484 Like "get_multi_arrayref", but returns a hash reference with each
485 key in $keys mapping to its corresponding value or undef. Will only
486 work with scalar keys.
487 set_multi( $key_values, $set_options )
489 Set the multiple keys and values provided in hash reference
490 $key_values. $set_options is a scalar or hash reference, used as
491 the third argument to set. Will only work with scalar keys.
492 remove_multi( $keys )
494 Removes the keys in list reference $keys.
495 dump_as_hash( )
497 Returns a hash reference containing all the non-expired keys and
498 values in the cache.
499 Property accessors
501 chi_root_class( )
502 Returns the name of the root class under which this object was
503 created, e.g. "CHI" or "My::CHI". See "SUBCLASSING AND CONFIGURING
504 CHI".
505 driver_class( )
507 Returns the full name of the driver class. e.g.
508 CHI->new(driver=>'File')->driver_class
510 => CHI::Driver::File
511 CHI->new(driver=>'+CHI::Driver::File')->driver_class
512 => CHI::Driver::File
513 CHI->new(driver=>'+My::Driver::File')->driver_class
514 => My::Driver::File
515 You should use this rather than ref(). Due to some subclassing
517 tricks CHI employs, the actual class of the object is neither
518 guaranteed nor likely to be the driver class.
519 short_driver_name( )
521 Returns the name of the driver class, minus the CHI::Driver::
522 prefix, if any. e.g.
523 CHI->new(driver=>'File')->short_driver_name
525 => File
526 CHI->new(driver_class=>'CHI::Driver::File')->short_driver_name
527 => File
528 CHI->new(driver_class=>'My::Driver::File')->short_driver_name
529 => My::Driver::File
530 Standard read-write accessors
532 expires_in
533 expires_at
534 expires_variance
535 label
536 on_get_error
537 on_set_error
538 Standard read-only accessors
540 namespace
541 serializer
542 Deprecated methods
544 The following methods are deprecated and will be removed in a later
545 version:
546 is_empty
548
550 Duration expressions, which appear in the "set" command and various
551 other parts of the API, are parsed by Time::Duration::Parse. A
552 duration is either a plain number, which is treated like a number of
553 seconds, or a number and a string representing time units where the
554 string is one of:
555 s second seconds sec secs
557 m minute minutes min mins
558 h hr hour hours
559 d day days
560 w week weeks
561 M month months
562 y year years
563 e.g. the following are all valid duration expressions:
565 25
567 3s
568 5 seconds
569 1 minute and ten seconds
570 1 hour
571
573 CHI strives to accept arbitrary keys and values for caching regardless
574 of the limitations of the underlying driver.
575 Key transformations
577 • Keys that are references are serialized - see "key_serializer".
578 • Keys with wide (>255) characters are utf8 encoded.
580 • Keys exceeding the maximum length for the underlying driver are
582 digested - see "max_key_length" and "key_digester".
583 • For some drivers (e.g. CHI::Driver::File), keys containing special
585 characters or whitespace are escaped with URL-like escaping.
586 Note: All transformations above with the exception of escaping are one-
588 way, meaning that CHI does not attempt to undo them when returned from
589 "get_keys"; and idempotent, meaning that applying them a second time
590 has no effect. So when you call "get_keys", the key you get may not be
591 exactly what you passed in, but you'll be able to pass that key in to
592 get the corresponding object.
593 Value transformations
595 • Values which are references are automatically serialized before
596 storing, and deserialized after retrieving - see "serializer".
597 • Values with their utf8 flag on are utf8 encoded before storing, and
599 utf8 decoded after retrieving.
600
602 It is possible to a cache to have one or more subcaches. There are
603 currently two types of subcaches: L1 and mirror.
604 L1 cache
606 An L1 (or "level one") cache sits in front of the primary cache,
607 usually to provide faster access for commonly accessed cache entries.
608 For example, this places an in-process Memory cache in front of a
609 Memcached cache:
610 my $cache = CHI->new(
612 driver => 'Memcached',
613 servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
614 l1_cache => { driver => 'Memory', global => 1, max_size => 1024*1024 }
615 );
616 On a "get", the L1 cache is checked first - if a valid value exists, it
618 is returned. Otherwise, the primary cache is checked - if a valid value
619 exists, it is returned, and the value is placed in the L1 cache with
620 the same expiration time. In this way, items fetched most frequently
621 from the primary cache will tend to be in the L1 cache.
622 "set" operations are distributed to both the primary and L1 cache.
624 You can access the L1 cache with the "l1_cache" method. For example,
626 this clears the L1 cache but leaves the primary cache intact:
627 $cache->l1_cache->clear();
629 Mirror cache
631 A mirror cache is a write-only cache that, over time, mirrors the
632 content of the primary cache. "set" operations are distributed to both
633 the primary and mirror cache, but "get" operations go only to the
634 primary cache.
635 Mirror caches are useful when you want to migrate from one cache to
637 another. You can populate a mirror cache and switch over to it once it
638 is sufficiently populated. For example, here we migrate from an old to
639 a new cache directory:
640 my $cache = CHI->new(
642 driver => 'File',
643 root_dir => '/old/cache/root',
644 mirror_cache => { driver => 'File', root_dir => '/new/cache/root' },
645 );
646 We leave this running for a few hours (or as needed), then replace it
648 with
649 my $cache = CHI->new(
651 driver => 'File',
652 root_dir => '/new/cache/root'
653 );
654 You can access the mirror cache with the "mirror_cache" method. For
656 example, to see how many keys have made it over to the mirror cache:
657 my @keys = $cache->mirror_cache->get_keys();
659 Creating subcaches
661 As illustrated above, you create subcaches by passing the "l1_cache"
662 and/or "mirror_cache" option to the CHI constructor. These options, in
663 turn, should contain a hash of options to create the subcache with.
664 The cache containing the subcache is called the parent cache.
666 The following options are automatically inherited by the subcache from
668 the parent cache, and may not be overridden:
669 expires_at
671 expires_in
672 expires_variance
673 serializer
674 (Reason: for efficiency, we want to create a single cache object and
676 store it in both caches. The cache object contains expiration
677 information and is dependent on the serializer. At some point we could
678 conceivably add code that will use a single object or separate objects
679 as necessary, and thus allow the above to be overridden.)
680 The following options are automatically inherited by the subcache from
682 the parent cache, but may be overridden:
683 namespace
685 on_get_error
686 on_set_error
687 All other options are initialized in the subcache as normal,
689 irrespective of their values in the parent.
690 It is not currently possible to pass an existing cache in as a
692 subcache.
693 Common subcache behaviors
695 These behaviors hold regardless of the type of subcache.
696 The following methods are distributed to both the primary cache and
698 subcache:
699 clear
701 expire
702 purge
703 remove
704 The following methods return information solely from the primary cache.
706 However, you are free to call them explicitly on the subcache. (Trying
707 to merge in subcache information automatically would require too much
708 guessing about the caller's intent.)
709 get_keys
711 get_namespaces
712 get_object
713 get_expires_at
714 exists_and_is_expired
715 is_valid
716 dump_as_hash
717 Multiple subcaches
719 It is valid for a cache to have one of each kind of subcache, e.g. an
720 L1 cache and a mirror cache.
721 A cache cannot have more than one of each kind of subcache, but a
723 subcache can have its own subcaches, and so on. e.g.
724 my $cache = CHI->new(
726 driver => 'Memcached',
727 servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
728 l1_cache => {
729 driver => 'File',
730 root_dir => '/path/to/root',
731 l1_cache => { driver => 'RawMemory', global => 1 }
732 }
733 );
734 Methods for parent caches
736 has_subcaches( )
737 Returns a boolean indicating whether this cache has subcaches.
738 l1_cache( )
740 Returns the L1 cache for this cache, if any. Can only be called if
741 has_subcaches is true.
742 mirror_cache( )
744 Returns the mirror cache for this cache, if any. Can only be called
745 if has_subcaches is true.
746 subcaches( )
748 Returns the subcaches for this cache, in arbitrary order. Can only
749 be called if has_subcaches is true.
750 Methods for subcaches
752 is_subcache( )
753 Returns a boolean indicating whether this is a subcache.
754 subcache_type( )
756 Returns the type of subcache as a string, e.g. 'l1_cache' or
757 'mirror_cache'. Can only be called if is_subcache is true.
758 parent_cache( )
760 Returns the parent cache (weakened to prevent circular reference).
761 Can only be called if is_subcache is true.
762 Developing new kinds of subcaches
764 At this time, subcache behavior is hardcoded into CHI::Driver, so there
765 is no easy way to modify the behavior of existing subcache types or
766 create new ones. We'd like to make this more flexible eventually.
767
769 If "is_size_aware" or "max_size" are passed to the constructor, the
770 cache will be size aware - that is, it will keep track of its own size
771 (in bytes) as items are added and removed. You can get a cache's size
772 with "get_size".
773 Size aware caches generally keep track of their size in a separate
775 meta-key, and have to do an extra store whenever the size changes (e.g.
776 on each set and remove).
777 Maximum size and discard policies
779 If a cache's size rises above its "max_size", items are discarded until
780 the cache size is sufficiently below the max size. (See
781 "max_size_reduction_factor" for how to fine-tune this.)
782 The order in which items are discarded is controlled with
784 "discard_policy". The default discard policy is 'arbitrary', which
785 discards items in an arbitrary order. The available policies and
786 default policy can differ with each driver, e.g. the
787 CHI::Driver::Memory driver provides and defaults to an 'LRU' policy.
788 Appropriate drivers
790 Size awareness was chiefly designed for, and works well with, the
791 CHI::Driver::Memory driver: one often needs to enforce a maximum size
792 on a memory cache, and the overhead of tracking size in memory is
793 negligible. However, the capability may be useful with other drivers.
794 Some drivers - for example, CHI::Driver::FastMmap and
796 CHI::Driver::Memcached - inherently keep track of their size and
797 enforce a maximum size, and it makes no sense to turn on CHI's size
798 awareness for these.
799 Also, for drivers that cannot atomically read and update a value - for
801 example, CHI::Driver::File - there is a race condition in the updating
802 of size that can cause the size to grow inaccurate over time.
803
805 You can subclass CHI for your own application and configure it in a
806 variety of ways, e.g. predefining storage types and defaults for new
807 cache objects. Your configuration will be independent of the main CHI
808 class and other CHI subclasses.
809 Start with a trivial subclass:
811 package My::CHI;
813 use base qw(CHI);
815 1;
816 Then, just use your subclass in place of CHI:
818 my $cache = My::CHI->new( ... );
820 print $cache->chi_root_class;
822 ==> 'My::CHI'
823 This obviously doesn't change any behavior by itself. Here's an example
825 with actual config:
826 package My::CHI;
828 use base qw(CHI);
830 __PACKAGE__->config({
832 storage => {
833 local_file => { driver => 'File', root_dir => '/my/root' },
834 memcached => {
835 driver => 'Memcached::libmemcached',
836 servers => [ '10.0.0.15:11211', '10.0.0.15:11212' ]
837 },
838 },
839 namespace => {
840 'Foo' => { storage => 'local_file' },
841 'Bar' => { storage => 'local_file', depth => 3 },
842 'Baz' => { storage => 'memcached' },
843 }
844 defaults => { storage => 'local_file' },
845 memoize_cache_objects => 1,
846 });
847 1;
849 Each of these config keys is explained in the next section.
851 Configuration keys
853 storage
854 A map of names to parameter hashrefs. This provides a way to
855 encapsulate common sets of parameters that might be used in many
856 caches. e.g. if you define
857 storage => {
859 local_file => { driver => 'File', root_dir => '/my/root' },
860 ...
861 }
862 then
864 my $cache = My::CHI->new
866 (namespace => 'Foo', storage => 'local_file');
867 is equivalent to
869 my $cache = My::CHI->new
871 (namespace => 'Foo', driver => 'File', root_dir => '/my/root');
872 namespace
874 A map of namespace names to parameter hashrefs. When you create a
875 cache object with the specified namespace, the hashref of
876 parameters will be applied as defaults. e.g. if you define
877 namespace => {
879 'Foo' => { driver => 'File', root_dir => '/my/root' },
880 'Bar' => { storage => 'database' },
881 ...
882 }
883 then
885 my $cache1 = My::CHI->new
887 (namespace => 'Foo');
888 my $cache2 = My::CHI->new
889 (namespace => 'Bar');
890 is equivalent to
892 my $cache1 = My::CHI->new
894 (namespace => 'Foo', driver => 'File', root_dir => '/my/root');
895 my $cache2 = My::CHI->new
896 (namespace => 'Bar', storage => 'database');
897 defaults
899 A hash of parameters that will be used as core defaults for all
900 cache objects created under this root class. e.g.
901 defaults => {
903 on_get_error => 'die',
904 expires_variance => 0.2,
905 }
906 These can be overridden by namespace defaults, storage settings, or
908 "new" parameters.
909 memoize_cache_objects
911 True or false, indicates whether "My::CHI->new" should memoize and
912 return the same cache object if given the same parameters. This can
913 speed things up if you create cache objects frequently. Will
914 currently only work for 0- or 1- key parameter hashes. e.g.
915 My::CHI->config({
917 memoize_cache_objects => 1,
918 });
919 then
921 # $cache1 and $cache2 will be the same object, regardless of what
923 # namespace and storage defaults are associated with 'Foo'
924 #
925 my $cache1 = My::CHI->new(namespace => 'Foo');
926 my $cache2 = My::CHI->new(namespace => 'Foo');
927 # $cache3 and $cache4 will be different objects
929 #
930 my $cache3 = My::CHI->new
931 (namespace => 'Bar', driver => 'File', root_dir => '/my/root');
932 my $cache4 = My::CHI->new
933 (namespace => 'Bar', driver => 'File', root_dir => '/my/root');
934 To clear the memoized cache objects, call
936 My::CHI->clear_memoized_cache_objects;
938 How defaults are combined
940 Defaults are applied in the following order, from highest to lowest
941 precedence:
942 • Parameters passed in "new"
944 • Namespace defaults, if any
946 • Storage settings, if any
948 • Core defaults defined under 'defaults'
950 Inheritance of config
952 A subclass will automatically inherit the configuration of its parent
953 if it does not call "config" itself (ala Class::Data::Inheritable).
954 Reading config from a file
956 use YAML::XS qw(LoadFile);
957 __PACKAGE__->config(LoadFile("/path/to/cache.yml"));
959
961 The following drivers are currently available as part of this
962 distribution:
963 • CHI::Driver::Memory - In-process memory based cache
965 • CHI::Driver::RawMemory - In-process memory based cache that stores
967 references directly instead of serializing/deep-copying
968 • CHI::Driver::File - File-based cache using one file per entry in a
970 multi-level directory structure
971 • CHI::Driver::FastMmap - Shared memory interprocess cache via
973 mmap'ed files
974 • CHI::Driver::Null - Dummy cache in which nothing is stored
976 • CHI::Driver::CacheCache - CHI wrapper for Cache::Cache
978 The following drivers are currently available as separate CPAN
980 distributions:
981 • CHI::Driver::Memcached - Distributed memory-based cache (works with
983 Cache::Memcached, Cache::Memcached::Fast, and
984 Cache::Memcached::libmemcached)
985 • CHI::Driver::DBI - Cache in any DBI-supported database
987 • CHI::Driver::BerkeleyDB - Cache in BerkeleyDB files
989 • CHI::Driver::Redis - Cache in Redis <http://redis.io/>
991 • CHI::Driver::SharedMem - Cache in shared memory
993 This list is likely incomplete. A complete set of drivers can be found
995 on CPAN by searching for "CHI::Driver".
996
998 See CHI::Benchmarks for a comparison of read/write times of both CHI
999 and non-CHI cache implementations.
1000 "etc/bench/bench.pl" in the "CHI" distribution contains a script to run
1002 these types of benchmarks on your own system.
1003
1005 See CHI::Driver::Development for information on developing new drivers.
1006
1008 "CHI" uses Log::Any for logging events. For example, a debug log
1009 message is sent with category "CHI::Driver" for every cache get and
1010 set.
1011 See Log::Any documentation for how to control where logs get sent, if
1013 anywhere.
1014
1016 CHI can record statistics, such as number of hits, misses and sets, on
1017 a per-namespace basis and log the results to your Log::Any logger. You
1018 can then use utilities included with this distribution to read stats
1019 back from the logs and report a summary. See CHI::Stats for details.
1020
1022 Cache::Cache
1023 CHI is intended as an evolution of DeWitt Clinton's Cache::Cache
1024 package. It starts with the same basic API (which has proven durable
1025 over time) but addresses some implementation shortcomings that cannot
1026 be fixed in Cache::Cache due to backward compatibility concerns. In
1027 particular:
1028 Performance
1030 Some of Cache::Cache's subclasses (e.g. Cache::FileCache) have been
1031 justifiably criticized as inefficient. CHI has been designed from
1032 the ground up with performance in mind, both in terms of general
1033 overhead and in the built-in driver classes. Method calls are kept
1034 to a minimum, data is only serialized when necessary, and metadata
1035 such as expiration time is stored in packed binary format alongside
1036 the data.
1037 Ease of subclassing
1039 New Cache::Cache subclasses can be tedious to create, due to a lack
1040 of code refactoring, the use of non-OO package subroutines, and the
1041 separation of "cache" and "backend" classes. With CHI, the goal is
1042 to make the creation of new drivers as easy as possible, roughly
1043 the same as writing a TIE interface to your data store. Concerns
1044 like serialization and expiration options are handled by the driver
1045 base class so that individual drivers don't have to worry about
1046 them.
1047 Increased compatibility with cache implementations
1049 Probably because of the reasons above, Cache::Cache subclasses were
1050 never created for some of the most popular caches available on
1051 CPAN, e.g. Cache::FastMmap and Cache::Memcached. CHI's goal is to
1052 be able to support these and other caches with a minimum
1053 performance overhead and minimum of glue code required.
1054 Cache
1056 The Cache distribution is another redesign and implementation of Cache,
1057 created by Chris Leishman in 2003. Like CHI, it improves performance
1058 and reduces the barrier to implementing new cache drivers. It breaks
1059 with the Cache::Cache interface in a few ways that I considered non-
1060 negotiable - for example, get/set do not serialize data, and namespaces
1061 are an optional feature that drivers may decide not to implement.
1062 Cache::Memcached, Cache::FastMmap, etc.
1064 CPAN sports a variety of full-featured standalone cache modules
1065 representing particular backends. CHI does not reinvent these but
1066 simply wraps them with an appropriate driver. For example,
1067 CHI::Driver::Memcached and CHI::Driver::FastMmap are thin layers around
1068 Cache::Memcached and Cache::FastMmap.
1069 Of course, because these modules already work on their own, there will
1071 be some overlap. Cache::FastMmap, for example, already has code to
1072 serialize data and handle expiration times. Here's how CHI resolves
1073 these overlaps.
1074 Serialization
1076 CHI handles its own serialization, passing a flat binary string to
1077 the underlying cache backend. The notable exception is
1078 CHI::Driver::RawMemory which does no serialization.
1079 Expiration
1081 CHI packs expiration times (as well as other metadata) inside the
1082 binary string passed to the underlying cache backend. The backend
1083 is unaware of these values; from its point of view the item has no
1084 expiration time. Among other things, this means that you can use
1085 CHI to examine expired items (e.g. with $cache->get_object) even if
1086 this is not supported natively by the backend.
1087 At some point CHI will provide the option of explicitly notifying
1089 the backend of the expiration time as well. This might allow the
1090 backend to do better storage management, etc., but would prevent
1091 CHI from examining expired items.
1092 Naturally, using CHI's FastMmap or Memcached driver will never be as
1094 time or storage efficient as simply using Cache::FastMmap or
1095 Cache::Memcached. In terms of performance, we've attempted to make the
1096 overhead as small as possible, on the order of 5% per get or set
1097 (benchmarks coming soon). In terms of storage size, CHI adds about 16
1098 bytes of metadata overhead to each item. How much this matters
1099 obviously depends on the typical size of items in your cache.
1100
1102 Questions and feedback are welcome, and should be directed to the perl-
1103 cache mailing list:
1104 http://groups.google.com/group/perl-cache-discuss
1106 Bugs and feature requests will be tracked at RT:
1108 http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI
1110 bug-chi@rt.cpan.org
1111 The latest source code can be browsed and fetched at:
1113 http://github.com/jonswar/perl-chi/tree/master
1115 git clone git://github.com/jonswar/perl-chi.git
1116
1118 Thanks to Dewitt Clinton for the original Cache::Cache, to Rob Mueller
1119 for the Perl cache benchmarks, and to Perrin Harkins for the
1120 discussions that got this going.
1121 CHI was originally designed and developed for the Digital Media group
1123 of the Hearst Corporation, a diversified media company based in New
1124 York City. Many thanks to Hearst management for agreeing to this open
1125 source release.
1126
1128 Cache::Cache
1129
1131 Jonathan Swartz <swartz@pobox.com>
1132
1134 This software is copyright (c) 2021 by Jonathan Swartz.
1135 This is free software; you can redistribute it and/or modify it under
1137 the same terms as the Perl 5 programming language system itself.
1138perl v5.36.0 2023-01-20 CHI(3)