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

NAME

6       CHI - Unified cache handling interface
7

VERSION

9       version 0.60
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 will be called with the hash. You will
212           need to ensure Data::Serializer is installed to use these options.
213
214           Otherwise, this must be a Data::Serializer object or another object
215           that implements serialize() and deserialize().
216
217           e.g.
218
219               # Serialize using raw Data::Dumper
220               my $cache = CHI->new(serializer => 'Data::Dumper');
221
222               # Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex-encoded
223               my $cache = CHI->new(serializer => { serializer => 'Data::Dumper', compress => 1 });
224
225               # Serialize using custom object
226               my $cache = CHI->new(serializer => My::Custom::Serializer->new())
227
228           The default is to use raw Storable.
229
230       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
235               traits => ['StoresAccessedAt', '+My::CHI::Driver::Role']
236

INSTANCE METHODS

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
241   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
247           $key may be followed by one or more name/value parameters:
248
249           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
256                   $cache->get('foo', expire_if => sub { $_[0]->created_at < (stat($file))[9] });
257
258           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
267           obj_ref [SCALARREF]
268               If the item exists in cache (even if expired), place the
269               CHI::CacheObject object in the provided SCALARREF.
270
271       set( $key, $data, [$expires_in | "now" | "never" | options] )
272           Associates $data with $key in the cache, overwriting any existing
273           entry.  Returns $data.
274
275           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
282           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
286           expires_at [INT]
287               The epoch time at which the data expires.
288
289           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
294               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
301               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
306               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
311                   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
315                   my $cache = CHI->new ( ... );
316                   $cache->set($key, $value, { expires_in => '20 min', expires_variance => 0.25 });
317
318               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
323                   my $value = $cache->get($key);     # returns undef (indicating expired)
324                   my $value = $cache->get($key);     # returns valid value this time!
325
326                   if ($cache->is_valid($key))        # returns undef (indicating expired)
327                   if ($cache->is_valid($key))        # returns true this time!
328
329               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
333       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
339           $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
345               # No expiration
346               my $value = $cache->compute($key, undef, sub {
347                   # compute and return value for $key here
348               });
349
350               # Expire in 5 minutes
351               my $value = $cache->compute($key, '5min', sub {
352                   # compute and return value for $key here
353               });
354
355               # 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
362               # List context
363               my @value = $cache->compute($key, '5min', sub {
364                   ...
365                   return @some_list;
366               });
367
368           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
372           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
376   Removing and expiring
377       remove( $key )
378           Remove the data associated with the $key from the cache.
379
380       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
386   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
392       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
397       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
401       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
407   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
412       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
418       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
422       add( $key, $data, [$expires_in | "now" | "never" | options] )
423           Do a set, but only if $key is not valid in the cache.
424
425       replace( $key, $data, [$expires_in | "now" | "never" | options] )
426           Do a set, but only if $key is valid in the cache.
427
428       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
432           Returns true if $key was in the cache, false otherwise.
433
434           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
440           Does not modify expiration or other metadata. If $key exists but is
441           expired, it will remain expired.
442
443           If you use a driver with the non-atomic (default) implementation,
444           some appends may be lost due to race conditions.
445
446   Namespace operations
447       clear( )
448           Remove all entries from the namespace.
449
450       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
454           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
461             map { ($_, $c->get($_)) } $c->get_keys()
462
463       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
468       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
472   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
478       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
482       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
487       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
492       remove_multi( $keys )
493           Removes the keys in list reference $keys.
494
495       dump_as_hash( )
496           Returns a hash reference containing all the non-expired keys and
497           values in the cache.
498
499   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
505       driver_class( )
506           Returns the full name of the driver class. e.g.
507
508               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
515           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
519       short_driver_name( )
520           Returns the name of the driver class, minus the CHI::Driver::
521           prefix, if any.  e.g.
522
523               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
530       Standard read-write accessors
531               expires_in
532               expires_at
533               expires_variance
534               label
535               on_get_error
536               on_set_error
537
538       Standard read-only accessors
539               namespace
540               serializer
541
542   Deprecated methods
543       The following methods are deprecated and will be removed in a later
544       version:
545
546           is_empty
547

DURATION EXPRESSIONS

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

KEY AND VALUE TRANSFORMATIONS

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

SUBCACHES

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

SIZE AWARENESS

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
773       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
777   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
782       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
788   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
794       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
799       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

SUBCLASSING AND CONFIGURING CHI

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

AVAILABILITY OF DRIVERS

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

PERFORMANCE COMPARISON OF DRIVERS

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

DEVELOPING NEW DRIVERS

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

LOGGING

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

STATS

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

RELATION TO OTHER MODULES

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
1028       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
1037       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
1047       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
1054   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
1062   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
1069       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
1074       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
1079       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
1087           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
1092       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

SUPPORT AND DOCUMENTATION

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

ACKNOWLEDGMENTS

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

SEE ALSO

1127       Cache::Cache
1128

AUTHOR

1130       Jonathan Swartz <swartz@pobox.com>
1131
1133       This software is copyright (c) 2012 by Jonathan Swartz.
1134
1135       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.
1137
1138
1139
1140perl v5.32.1                      2021-01-26                            CHI(3)
Impressum