1CHI(3)                User Contributed Perl Documentation               CHI(3)
2
3
4

NAME

6       CHI - Unified cache handling interface
7

VERSION

9       version 0.61
10

SYNOPSIS

12           use CHI;
13
14           # 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
36           # Create your own driver
37           #
38           my $cache = CHI->new( driver => '+My::Special::Driver', ... );
39
40           # 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

DESCRIPTION

53       CHI provides a unified caching API, designed to assist a developer in
54       persisting data for a specified period of time.
55
56       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
61       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

FEATURES

66       •   Easy to create new drivers
67
68       •   Uniform support for namespaces
69
70       •   Automatic serialization of keys and values
71
72       •   Multilevel caches
73
74       •   Probabilistic expiration and busy locks, to reduce cache miss
75           stampedes
76
77       •   Optional logging and statistics collection of cache activity
78

CONSTRUCTOR

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
83       Some drivers will take additional constructor options. For example, the
84       File driver takes "root_dir" and "depth" options.
85
86       You can configure default options for each new cache object created -
87       see "SUBCLASSING AND CONFIGURING CHI".
88
89       Note that "CHI->new" returns an instance of a subclass of CHI::Driver,
90       not "CHI".
91
92       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
98               # Compress values larger than 1MB
99               compress_threshold => 1024*1024
100
101       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
106               driver => 'File';                   # uses CHI::Driver::File
107               driver => '+My::CHI::Driver::File'  # uses My::CHI::Driver::File
108
109       expires_in [DURATION], expires_at [INT], expires_variance [FLOAT]
110           Provide default values for the corresponding "set" options.
111
112       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
117           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
123           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
128       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
132           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
136           Default is "MD5".
137
138       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
144       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
150       l1_cache [HASHREF]
151           Add an L1 cache as a subcache. See "SUBCACHES".
152
153       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
158       mirror_cache [HASHREF]
159           Add an mirror cache as a subcache. See "SUBCACHES".
160
161       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
166           Suggestions for easy namespace selection:
167
168           •   In a class, use the class name:
169
170                   my $cache = CHI->new(namespace => __PACKAGE__, ...);
171
172           •   In a script, use the script's absolute path name:
173
174                   use Cwd qw(realpath);
175                   my $cache = CHI->new(namespace => realpath($0), ...);
176
177           •   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
181           Defaults to 'Default' if not specified.
182
183       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
189           •   log (the default) - log an error, or ignore if no logger is set
190               - see "LOGGING"
191
192           •   ignore - do nothing
193
194           •   warn - call warn() with an appropriate message
195
196           •   die - call die() with an appropriate message
197
198coderef - call this code reference with three arguments: an
199               appropriate message, the key, and the original raw error
200               message
201
202       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
208           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
215           Otherwise, this must be a Data::Serializer object or another object
216           that implements serialize() and deserialize().
217
218           e.g.
219
220               # Serialize using raw Data::Dumper
221               my $cache = CHI->new(serializer => 'Data::Dumper');
222
223               # Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex-encoded
224               my $cache = CHI->new(serializer => { serializer => 'Data::Dumper', compress => 1 });
225
226               # Serialize using custom object
227               my $cache = CHI->new(serializer => My::Custom::Serializer->new())
228
229           The default is to use raw Storable.
230
231       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
236               traits => ['StoresAccessedAt', '+My::CHI::Driver::Role']
237

INSTANCE METHODS

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
242   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
248           $key may be followed by one or more name/value parameters:
249
250           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
257                   $cache->get('foo', expire_if => sub { $_[0]->created_at < (stat($file))[9] });
258
259           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
268           obj_ref [SCALARREF]
269               If the item exists in cache (even if expired), place the
270               CHI::CacheObject object in the provided SCALARREF.
271
272       set( $key, $data, [$expires_in | "now" | "never" | options] )
273           Associates $data with $key in the cache, overwriting any existing
274           entry.  Returns $data.
275
276           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
283           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
287           expires_at [INT]
288               The epoch time at which the data expires.
289
290           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
295               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
302               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
307               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
312                   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
316                   my $cache = CHI->new ( ... );
317                   $cache->set($key, $value, { expires_in => '20 min', expires_variance => 0.25 });
318
319               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
324                   my $value = $cache->get($key);     # returns undef (indicating expired)
325                   my $value = $cache->get($key);     # returns valid value this time!
326
327                   if ($cache->is_valid($key))        # returns undef (indicating expired)
328                   if ($cache->is_valid($key))        # returns true this time!
329
330               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
334       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
340           $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
346               # No expiration
347               my $value = $cache->compute($key, undef, sub {
348                   # compute and return value for $key here
349               });
350
351               # Expire in 5 minutes
352               my $value = $cache->compute($key, '5min', sub {
353                   # compute and return value for $key here
354               });
355
356               # 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
363               # List context
364               my @value = $cache->compute($key, '5min', sub {
365                   ...
366                   return @some_list;
367               });
368
369           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
373           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
377   Removing and expiring
378       remove( $key )
379           Remove the data associated with the $key from the cache.
380
381       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
387   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
393       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
398       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
402       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
408   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
413       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
419       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
423       add( $key, $data, [$expires_in | "now" | "never" | options] )
424           Do a set, but only if $key is not valid in the cache.
425
426       replace( $key, $data, [$expires_in | "now" | "never" | options] )
427           Do a set, but only if $key is valid in the cache.
428
429       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
433           Returns true if $key was in the cache, false otherwise.
434
435           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
441           Does not modify expiration or other metadata. If $key exists but is
442           expired, it will remain expired.
443
444           If you use a driver with the non-atomic (default) implementation,
445           some appends may be lost due to race conditions.
446
447   Namespace operations
448       clear( )
449           Remove all entries from the namespace.
450
451       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
455           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
462             map { ($_, $c->get($_)) } $c->get_keys()
463
464       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
469       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
473   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
479       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
483       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
488       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
493       remove_multi( $keys )
494           Removes the keys in list reference $keys.
495
496       dump_as_hash( )
497           Returns a hash reference containing all the non-expired keys and
498           values in the cache.
499
500   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
506       driver_class( )
507           Returns the full name of the driver class. e.g.
508
509               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
516           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
520       short_driver_name( )
521           Returns the name of the driver class, minus the CHI::Driver::
522           prefix, if any.  e.g.
523
524               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
531       Standard read-write accessors
532               expires_in
533               expires_at
534               expires_variance
535               label
536               on_get_error
537               on_set_error
538
539       Standard read-only accessors
540               namespace
541               serializer
542
543   Deprecated methods
544       The following methods are deprecated and will be removed in a later
545       version:
546
547           is_empty
548

DURATION EXPRESSIONS

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
556           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
564       e.g. the following are all valid duration expressions:
565
566           25
567           3s
568           5 seconds
569           1 minute and ten seconds
570           1 hour
571

KEY AND VALUE TRANSFORMATIONS

573       CHI strives to accept arbitrary keys and values for caching regardless
574       of the limitations of the underlying driver.
575
576   Key transformations
577       •   Keys that are references are serialized - see "key_serializer".
578
579       •   Keys with wide (>255) characters are utf8 encoded.
580
581       •   Keys exceeding the maximum length for the underlying driver are
582           digested - see "max_key_length" and "key_digester".
583
584       •   For some drivers (e.g. CHI::Driver::File), keys containing special
585           characters or whitespace are escaped with URL-like escaping.
586
587       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
594   Value transformations
595       •   Values which are references are automatically serialized before
596           storing, and deserialized after retrieving - see "serializer".
597
598       •   Values with their utf8 flag on are utf8 encoded before storing, and
599           utf8 decoded after retrieving.
600

SUBCACHES

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
605   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
611           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
617       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
623       "set" operations are distributed to both the primary and L1 cache.
624
625       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
628           $cache->l1_cache->clear();
629
630   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
636       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
641           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
647       We leave this running for a few hours (or as needed), then replace it
648       with
649
650           my $cache = CHI->new(
651               driver   => 'File',
652               root_dir => '/new/cache/root'
653           );
654
655       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
658           my @keys = $cache->mirror_cache->get_keys();
659
660   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
665       The cache containing the subcache is called the parent cache.
666
667       The following options are automatically inherited by the subcache from
668       the parent cache, and may not be overridden:
669
670           expires_at
671           expires_in
672           expires_variance
673           serializer
674
675       (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
681       The following options are automatically inherited by the subcache from
682       the parent cache, but may be overridden:
683
684           namespace
685           on_get_error
686           on_set_error
687
688       All other options are initialized in the subcache as normal,
689       irrespective of their values in the parent.
690
691       It is not currently possible to pass an existing cache in as a
692       subcache.
693
694   Common subcache behaviors
695       These behaviors hold regardless of the type of subcache.
696
697       The following methods are distributed to both the primary cache and
698       subcache:
699
700           clear
701           expire
702           purge
703           remove
704
705       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
710           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
718   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
722       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
725           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
735   Methods for parent caches
736       has_subcaches( )
737           Returns a boolean indicating whether this cache has subcaches.
738
739       l1_cache( )
740           Returns the L1 cache for this cache, if any. Can only be called if
741           has_subcaches is true.
742
743       mirror_cache( )
744           Returns the mirror cache for this cache, if any. Can only be called
745           if has_subcaches is true.
746
747       subcaches( )
748           Returns the subcaches for this cache, in arbitrary order. Can only
749           be called if has_subcaches is true.
750
751   Methods for subcaches
752       is_subcache( )
753           Returns a boolean indicating whether this is a subcache.
754
755       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
759       parent_cache( )
760           Returns the parent cache (weakened to prevent circular reference).
761           Can only be called if is_subcache is true.
762
763   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

SIZE AWARENESS

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
774       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
778   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
783       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
789   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
795       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
800       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

SUBCLASSING AND CONFIGURING CHI

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
810       Start with a trivial subclass:
811
812           package My::CHI;
813
814           use base qw(CHI);
815           1;
816
817       Then, just use your subclass in place of CHI:
818
819           my $cache = My::CHI->new( ... );
820
821           print $cache->chi_root_class;
822              ==> 'My::CHI'
823
824       This obviously doesn't change any behavior by itself. Here's an example
825       with actual config:
826
827           package My::CHI;
828
829           use base qw(CHI);
830
831           __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
848           1;
849
850       Each of these config keys is explained in the next section.
851
852   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
858               storage => {
859                   local_file => { driver => 'File', root_dir => '/my/root' },
860                   ...
861               }
862
863           then
864
865               my $cache = My::CHI->new
866                  (namespace => 'Foo', storage => 'local_file');
867
868           is equivalent to
869
870               my $cache = My::CHI->new
871                  (namespace => 'Foo', driver => 'File', root_dir => '/my/root');
872
873       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
878               namespace => {
879                   'Foo' => { driver => 'File', root_dir => '/my/root' },
880                   'Bar' => { storage => 'database' },
881                   ...
882               }
883
884           then
885
886               my $cache1 = My::CHI->new
887                  (namespace => 'Foo');
888               my $cache2 = My::CHI->new
889                  (namespace => 'Bar');
890
891           is equivalent to
892
893               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
898       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
902               defaults => {
903                   on_get_error => 'die',
904                   expires_variance => 0.2,
905               }
906
907           These can be overridden by namespace defaults, storage settings, or
908           "new" parameters.
909
910       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
916               My::CHI->config({
917                   memoize_cache_objects => 1,
918               });
919
920           then
921
922               # $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
928               # $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
935           To clear the memoized cache objects, call
936
937               My::CHI->clear_memoized_cache_objects;
938
939   How defaults are combined
940       Defaults are applied in the following order, from highest to lowest
941       precedence:
942
943       •   Parameters passed in "new"
944
945       •   Namespace defaults, if any
946
947       •   Storage settings, if any
948
949       •   Core defaults defined under 'defaults'
950
951   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
955   Reading config from a file
956           use YAML::XS qw(LoadFile);
957
958           __PACKAGE__->config(LoadFile("/path/to/cache.yml"));
959

AVAILABILITY OF DRIVERS

961       The following drivers are currently available as part of this
962       distribution:
963
964       •   CHI::Driver::Memory - In-process memory based cache
965
966       •   CHI::Driver::RawMemory - In-process memory based cache that stores
967           references directly instead of serializing/deep-copying
968
969       •   CHI::Driver::File - File-based cache using one file per entry in a
970           multi-level directory structure
971
972       •   CHI::Driver::FastMmap - Shared memory interprocess cache via
973           mmap'ed files
974
975       •   CHI::Driver::Null - Dummy cache in which nothing is stored
976
977       •   CHI::Driver::CacheCache - CHI wrapper for Cache::Cache
978
979       The following drivers are currently available as separate CPAN
980       distributions:
981
982       •   CHI::Driver::Memcached - Distributed memory-based cache (works with
983           Cache::Memcached, Cache::Memcached::Fast, and
984           Cache::Memcached::libmemcached)
985
986       •   CHI::Driver::DBI - Cache in any DBI-supported database
987
988       •   CHI::Driver::BerkeleyDB - Cache in BerkeleyDB files
989
990       •   CHI::Driver::Redis - Cache in Redis <http://redis.io/>
991
992       •   CHI::Driver::SharedMem - Cache in shared memory
993
994       This list is likely incomplete. A complete set of drivers can be found
995       on CPAN by searching for "CHI::Driver".
996

PERFORMANCE COMPARISON OF DRIVERS

998       See CHI::Benchmarks for a comparison of read/write times of both CHI
999       and non-CHI cache implementations.
1000
1001       "etc/bench/bench.pl" in the "CHI" distribution contains a script to run
1002       these types of benchmarks on your own system.
1003

DEVELOPING NEW DRIVERS

1005       See CHI::Driver::Development for information on developing new drivers.
1006

LOGGING

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
1012       See Log::Any documentation for how to control where logs get sent, if
1013       anywhere.
1014

STATS

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

RELATION TO OTHER MODULES

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
1029       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
1038       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
1048       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
1055   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
1063   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
1070       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
1075       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
1080       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
1088           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
1093       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

SUPPORT AND DOCUMENTATION

1102       Questions and feedback are welcome, and should be directed to the perl-
1103       cache mailing list:
1104
1105           http://groups.google.com/group/perl-cache-discuss
1106
1107       Bugs and feature requests will be tracked at RT:
1108
1109           http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI
1110           bug-chi@rt.cpan.org
1111
1112       The latest source code can be browsed and fetched at:
1113
1114           http://github.com/jonswar/perl-chi/tree/master
1115           git clone git://github.com/jonswar/perl-chi.git
1116

ACKNOWLEDGMENTS

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
1122       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

SEE ALSO

1128       Cache::Cache
1129

AUTHOR

1131       Jonathan Swartz <swartz@pobox.com>
1132
1134       This software is copyright (c) 2021 by Jonathan Swartz.
1135
1136       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.
1138
1139
1140
1141perl v5.36.0                      2023-01-20                            CHI(3)
Impressum