CHI man page on Fedora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Fedora logo
[printable version]

CHI(3)		      User Contributed Perl Documentation		CHI(3)

NAME
       CHI - Unified cache handling interface

VERSION
       version 0.55

SYNOPSIS
	   use CHI;

	   # Choose a standard driver
	   #
	   my $cache = CHI->new( driver => 'Memory', global => 1 );
	   my $cache = CHI->new( driver => 'RawMemory', global => 1 );
	   my $cache = CHI->new( driver => 'File',
	       root_dir => '/path/to/root'
	   );
	   my $cache = CHI->new( driver => 'FastMmap',
	       root_dir	  => '/path/to/root',
	       cache_size => '1k'
	   );
	   my $cache = CHI->new( driver	 => 'Memcached::libmemcached',
	       servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
	       l1_cache => { driver => 'FastMmap', root_dir => '/path/to/root' }
	   );
	   my $cache = CHI->new( driver => 'DBI',
	       dbh => $dbh
	   );
	   my $cache = CHI->new( driver => 'BerkeleyDB',
	       root_dir => '/path/to/root'
	   );

	   # Create your own driver
	   #
	   my $cache = CHI->new( driver => '+My::Special::Driver', ... );

	   # Cache operations
	   #
	   my $customer = $cache->get($name);
	   if ( !defined $customer ) {
	       $customer = get_customer_from_db($name);
	       $cache->set( $name, $customer, "10 minutes" );
	   }
	   my $customer2 = $cache->compute($name2, "10 minutes", sub {
	       get_customer_from_db($name2)
	   });
	   $cache->remove($name);

DESCRIPTION
       CHI provides a unified caching API, designed to assist a developer in
       persisting data for a specified period of time.

       The CHI interface is implemented by driver classes that support
       fetching, storing and clearing of data. Driver classes exist or will
       exist for the gamut of storage backends available to Perl, such as
       memory, plain files, memory mapped files, memcached, and DBI.

       CHI is intended as an evolution of DeWitt Clinton's Cache::Cache
       package, adhering to the basic Cache API but adding new features and
       addressing limitations in the Cache::Cache implementation.

FEATURES
       ·   Easy to create new drivers

       ·   Uniform support for namespaces

       ·   Automatic serialization of keys and values

       ·   Multilevel caches

       ·   Probabilistic expiration and busy locks, to reduce cache miss
	   stampedes

       ·   Optional logging and statistics collection of cache activity

CONSTRUCTOR
       To create a new cache object, call "<CHI->new". It takes the common
       options listed below. driver is required; all others are optional.

       Some drivers will take additional constructor options. For example, the
       File driver takes "root_dir" and "depth" options.

       You can configure default options for each new cache object created -
       see "SUBCLASSING AND CONFIGURING CHI".

       Note that "CHI->new" returns an instance of a subclass of CHI::Driver,
       not "CHI".

       compress_threshold [INT]
	   A value in bytes. Automatically compress values larger than this
	   before storing.  Requires Compress::Zlib to be installed. Defaults
	   to undef, meaning no automatic compression. Inspired by the
	   parameter of the same name in Cache::Memcached.

	       # Compress values larger than 1MB
	       compress_threshold => 1024*1024

       driver [STRING]
	   Required. The name of a cache driver, for example "Memory" or
	   "File".  CHI will prefix the string with "CHI::Driver::", unless it
	   begins with '+'. e.g.

	       driver => 'File';		   # uses CHI::Driver::File
	       driver => '+My::CHI::Driver::File'  # uses My::CHI::Driver::File

       expires_in [DURATION], expires_at [INT], expires_variance [FLOAT]
	   Provide default values for the corresponding "set" options.

       expires_on_backend [NUM]
	   If set to 0 (the default), CHI alone is aware of the expiration
	   time and does not pass it along to the backend driver. This allows
	   you to use "get_object" to retrieve expired items.

	   If set to 1, pass expiration times to backend driver if the driver
	   supports it -- for example, CHI::Driver::Memcached and
	   CHI::Driver::CacheCache. This may allow the driver to better manage
	   its space and evict items. Note that only simple expiration time
	   will be passed along, e.g. not "expires_variance".

	   If set to a number greater than 1 (e.g. 1.25), the time til
	   expiration will be multiplied by that number before being passed to
	   the backend driver. This gives you a customizable window of
	   opportunity to retrieve expired items.

       key_digester [STRING|HASHREF|OBJECT]
	   Digest algorithm to use on keys longer than "max_key_length" - e.g.
	   "MD5", "SHA-1", or "SHA-256".

	   Can be a Digest object, or a string or hashref which will passed to
	   Digest->new(). You will need to ensure Digest is installed to use
	   these options.

	   Default is "MD5".

       key_serializer [STRING|HASHREF|OBJECT]
	   An object to use for serializing keys that are references. See
	   "serializer" above for the different ways this can be passed in.
	   The default is to use JSON in canonical mode (sorted hash keys).

       label [STRING]
	   A label for the cache as a whole, independent of namespace - e.g.
	   "web-file-cache". Used when referring to the cache in logs,
	   statistics, and error messages. By default, set to
	   "short_driver_name".

       l1_cache [HASHREF]
	   Add an L1 cache as a subcache. See "SUBCACHES".

       max_key_length [INT]
	   Keys over this size will be digested. The default is driver-
	   specific; CHI::Driver::File, for example, defaults this to 240 due
	   to file system limits. For most drivers there is no maximum.

       mirror_cache [HASHREF]
	   Add an mirror cache as a subcache. See "SUBCACHES".

       namespace [STRING]
	   Identifies a namespace that all cache entries for this object will
	   be in. This allows easy separation of multiple, distinct caches
	   without worrying about key collision.

	   Suggestions for easy namespace selection:

	   ·   In a class, use the class name:

		   my $cache = CHI->new(namespace => __PACKAGE__, ...);

	   ·   In a script, use the script's absolute path name:

		   use Cwd qw(realpath);
		   my $cache = CHI->new(namespace => realpath($0), ...);

	   ·   In a web template, use the template name. For example, in
	       Mason, $m->cache will set the namespace to the current
	       component path.

	   Defaults to 'Default' if not specified.

       on_get_error [STRING|CODEREF]
       on_set_error [STRING|CODEREF]
	   How to handle runtime errors occurring during cache gets and cache
	   sets, which may or may not be considered fatal in your application.
	   Options are:

	   ·   log (the default) - log an error, or ignore if no logger is set
	       - see "LOGGING"

	   ·   ignore - do nothing

	   ·   warn - call warn() with an appropriate message

	   ·   die - call die() with an appropriate message

	   ·   coderef - call this code reference with three arguments: an
	       appropriate message, the key, and the original raw error
	       message

       serializer [STRING|HASHREF|OBJECT]
	   An object to use for serializing data before storing it in the
	   cache, and deserializing data after retrieving it from the cache.
	   Only references will be serialized; plain scalars will be placed in
	   the cache as-is.

	   If this is a string, a Data::Serializer object will be created,
	   with the string passed as the 'serializer' option and raw=1. Common
	   options include 'Storable', 'Data::Dumper', and 'YAML'. If this is
	   a hashref, Data::Serializer will be called with the hash. You will
	   need to ensure Data::Serializer is installed to use these options.

	   Otherwise, this must be a Data::Serializer object or another object
	   that implements serialize() and deserialize().

	   e.g.

	       # Serialize using raw Data::Dumper
	       my $cache = CHI->new(serializer => 'Data::Dumper');

	       # Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex-encoded
	       my $cache = CHI->new(serializer => { serializer => 'Data::Dumper', compress => 1 });

	       # Serialize using custom object
	       my $cache = CHI->new(serializer => My::Custom::Serializer->new())

	   The default is to use raw Storable.

       traits [LISTREF]
	   List of one or more roles to apply to the "CHI::Driver" class that
	   is constructed. The roles will automatically be prefixed with
	   "CHI::Driver::Role::" unless preceded with a '+'. e.g.

	       traits => ['StoresAccessedAt', '+My::CHI::Driver::Role']

INSTANCE METHODS
       The following methods can be called on any cache handle returned from
       CHI->new(). They are implemented in the CHI::Driver package.

   Getting and setting
       get( $key, [option => value, ...] )
	   Returns the data associated with $key. If $key does not exist or
	   has expired, returns undef. Expired items are not automatically
	   removed and may be examined with "get_object" or "get_expires_at".

	   $key may be followed by one or more name/value parameters:

	   expire_if [CODEREF]
	       If $key exists and has not expired, call code reference with
	       the CHI::CacheObject as a single parameter. If code returns a
	       true value, "get" returns undef as if the item were expired.
	       For example, to treat the cache as expired if $file has changed
	       since the value was computed:

		   $cache->get('foo', expire_if => sub { $_[0]->created_at < (stat($file))[9] });

	   busy_lock [DURATION]
	       If the value has expired, the get will still return undef, but
	       the expiration time of the cache entry will be set to the
	       current time plus the specified duration.  This is used to
	       prevent multiple processes from recomputing the same expensive
	       value simultaneously. The problem with this technique is that
	       it doubles the number of writes performed - see
	       "expires_variance" for another technique.

	   obj_ref [SCALARREF]
	       If the item exists in cache, place the
	       <CHI::CacheObject|CHI::CacheObject> object in the provided
	       SCALARREF.

       set( $key, $data, [$expires_in | "now" | "never" | options] )
	   Associates $data with $key in the cache, overwriting any existing
	   entry.  Returns $data.

	   The third argument to "set" is optional, and may be either a scalar
	   or a hash reference. If it is a scalar, it may be the string "now",
	   the string "never", or else a duration treated as an expires_in
	   value described below. If it is a hash reference, it may contain
	   one or more of the following options. Most of these options can be
	   provided with defaults in the cache constructor.

	   expires_in [DURATION]
	       Amount of time from now until this data expires. DURATION may
	       be an integer number of seconds or a duration expression.

	   expires_at [INT]
	       The epoch time at which the data expires.

	   expires_variance [FLOAT]
	       Controls the variable expiration feature, which allows items to
	       expire a little earlier than the stated expiration time to help
	       prevent cache miss stampedes.

	       Value is between 0.0 and 1.0, with 0.0 meaning that items
	       expire exactly when specified (feature is disabled), and 1.0
	       meaning that items might expire anytime from now til the stated
	       expiration time. The default is 0.0. A setting of 0.10 to 0.25
	       would introduce a small amount of variation without interfering
	       too much with intended expiration times.

	       The probability of expiration increases as a function of how
	       far along we are in the potential expiration window, with the
	       probability being near 0 at the beginning of the window and
	       approaching 1 at the end.

	       For example, in all of the following cases, an item might be
	       considered expired any time between 15 and 20 minutes, with
	       about a 20% chance at 16 minutes, a 40% chance at 17 minutes,
	       and a 100% chance at 20 minutes.

		   my $cache = CHI->new ( ..., expires_variance => 0.25, ... );
		   $cache->set($key, $value, '20 min');
		   $cache->set($key, $value, { expires_at => time() + 20*60 });

		   my $cache = CHI->new ( ... );
		   $cache->set($key, $value, { expires_in => '20 min', expires_variance => 0.25 });

	       CHI will make a new probabilistic choice every time it needs to
	       know whether an item has expired (i.e. it does not save the
	       results of its determination), so you can get situations like
	       this:

		   my $value = $cache->get($key);     # returns undef (indicating expired)
		   my $value = $cache->get($key);     # returns valid value this time!

		   if ($cache->is_valid($key))	      # returns undef (indicating expired)
		   if ($cache->is_valid($key))	      # returns true this time!

	       Typical applications won't be affected by this, since the
	       object is recomputed as soon as it is determined to be expired.
	       But it's something to be aware of.

       compute( $key, $options, $code )
	   Combines the "get" and "set" operations in a single call. Attempts
	   to get $key; if successful, returns the value. Otherwise, calls
	   $code and uses the return value as the new value for $key, which is
	   then returned. Caller context (scalar or list) is respected.

	   $options can be undef, a scalar, or a hash reference. If it is
	   undef, it has no effect. If it is a scalar, it is treated as the
	   "expires_in" duration and passed as the third argument to "set". If
	   it is a hash reference, it may contain name/value pairs for both
	   "get" and "set".  e.g.

	       # No expiration
	       my $value = $cache->compute($key, undef, sub {
		   # compute and return value for $key here
	       });

	       # Expire in 5 minutes
	       my $value = $cache->compute($key, '5min', sub {
		   # compute and return value for $key here
	       });

	       # Expire in 5 minutes or when a particular condition occurs
	       my $value = $cache->compute($key,
		   { expires_in => '5min', expire_if => sub { ... } },
		   sub {
		      # compute and return value for $key here
	       });

	       # List context
	       my @value = $cache->compute($key, '5min', sub {
		   ...
		   return @some_list;
	       });

	   This method will eventually support the ability to recompute a
	   value in the background just before it actually expires, so that
	   users are not impacted by recompute time.

	   Note: Prior to version 0.40, the last two arguments were in reverse
	   order; both will be accepted for backward compatibility. We think
	   the coderef looks better at the end.

   Removing and expiring
       remove( $key )
	   Remove the data associated with the $key from the cache.

       expire( $key )
	   If $key exists, expire it by setting its expiration time into the
	   past. Does not necessarily remove the data. Since this involves
	   essentially setting the value again, "remove" may be more efficient
	   for some drivers.

   Inspecting keys
       is_valid( $key )
	   Returns a boolean indicating whether $key exists in the cache and
	   has not expired. Note: Expiration may be determined
	   probabilistically if "expires_variance" was used.

       exists_and_is_expired( $key )
	   Returns a boolean indicating whether $key exists in the cache and
	   has expired.	 Note: Expiration may be determined probabilistically
	   if "expires_variance" was used.

       get_expires_at( $key )
	   Returns the epoch time at which $key definitively expires. Returns
	   undef if the key does not exist or it has no expiration time.

       get_object( $key )
	   Returns a CHI::CacheObject object containing data about the entry
	   associated with $key, or undef if no such key exists. The object
	   will be returned even if the entry has expired, as long as it has
	   not been removed.

   Atomic operations (ALPHA)
       These methods combine both reading and writing of a cache entry in a
       single operation. The names and behaviors were adapted from memcached
       <http://memcached.org/>.

       Some drivers (e.g.  CHI::Driver::Memcached::libmemcached,
       CHI::Driver::DBI) may implement these as truly atomic operations, and
       will be documented thusly.  The default implementations are not atomic:
       the get and set occur discretely and another process could potentially
       modify the cache in between them.

       These operations are labelled ALPHA because we haven't yet figured out
       how they integrate with other CHI features, in particular "SUBCACHES".
       APIs and behavior may change.

       add( $key, $data, [$expires_in | "now" | "never" | options] )
	   Do a set, but only if $key is not valid in the cache.

       replace( $key, $data, [$expires_in | "now" | "never" | options] )
	   Do a set, but only if $key is valid in the cache.

       append( $key, $new_data)
	   Append $new_data to whatever value is currently associated with
	   $key.  Does not modify expiration or other metadata; if $key exists
	   but is expired, it will remain expired. Has no effect if $key does
	   not exist in the cache.

	   This is intended for simple string values only. For efficiency's
	   sake, CHI won't attempt to check for, or handle, the case where
	   data is serialized or compressed; the new data will simply be
	   appended, and an error will most probably occur when you try to
	   retrieve the value.

	   If you use a driver with the non-atomic (default) implementation,
	   some appends may be lost due to race conditions.

   Namespace operations
       clear( )
	   Remove all entries from the namespace.

       get_keys( )
	   Returns a list of keys in the namespace. This may or may not
	   include expired keys, depending on the driver.

	   The keys may not look the same as they did when passed into "set";
	   they may have been serialized, utf8 encoded, and/or digested (see
	   "KEY AND VALUE TRANSFORMATIONS"). However, they may still be passed
	   back into "get", "set", etc. to access the same underlying objects.
	   i.e. the following code is guaranteed to produce all key/value
	   pairs from the cache:

	     map { ($_, $c->get($_)) } $c->get_keys()

       purge( )
	   Remove all entries that have expired from the namespace associated
	   with this cache instance. Warning: May be very inefficient,
	   depending on the number of keys and the driver.

       get_namespaces( )
	   Returns a list of namespaces associated with the cache. This may or
	   may not include empty namespaces, depending on the driver.

   Multiple key/value operations
       The methods in this section process multiple keys and/or values at
       once. By default these are implemented with the obvious map operations,
       but some cache drivers (e.g. Cache::Memcached) can override them with
       more efficient implementations.

       get_multi_arrayref( $keys )
	   Get the keys in list reference $keys, and return a list reference
	   of the same length with corresponding values or undefs.

       get_multi_hashref( $keys )
	   Like "get_multi_arrayref", but returns a hash reference with each
	   key in $keys mapping to its corresponding value or undef. Will only
	   work with scalar keys.

       set_multi( $key_values, $set_options )
	   Set the multiple keys and values provided in hash reference
	   $key_values.	 $set_options is a scalar or hash reference, used as
	   the third argument to set. Will only work with scalar keys.

       remove_multi( $keys )
	   Removes the keys in list reference $keys.

       dump_as_hash( )
	   Returns a hash reference containing all the non-expired keys and
	   values in the cache.

   Property accessors
       chi_root_class( )
	   Returns the name of the root class under which this object was
	   created, e.g.  "CHI" or "My::CHI". See "SUBCLASSING AND CONFIGURING
	   CHI".

       driver_class( )
	   Returns the full name of the driver class. e.g.

	       CHI->new(driver=>'File')->driver_class
		  => CHI::Driver::File
	       CHI->new(driver=>'+CHI::Driver::File')->driver_class
		  => CHI::Driver::File
	       CHI->new(driver=>'+My::Driver::File')->driver_class
		  => My::Driver::File

	   You should use this rather than "ref()". Due to some subclassing
	   tricks CHI employs, the actual class of the object is neither
	   guaranteed nor likely to be the driver class.

       short_driver_name( )
	   Returns the name of the driver class, minus the CHI::Driver::
	   prefix, if any.  e.g.

	       CHI->new(driver=>'File')->short_driver_name
		  => File
	       CHI->new(driver_class=>'CHI::Driver::File')->short_driver_name
		  => File
	       CHI->new(driver_class=>'My::Driver::File')->short_driver_name
		  => My::Driver::File

       Standard read-write accessors
	       expires_in
	       expires_at
	       expires_variance
	       label
	       on_get_error
	       on_set_error

       Standard read-only accessors
	       namespace
	       serializer

   Deprecated methods
       The following methods are deprecated and will be removed in a later
       version:

	   is_empty

DURATION EXPRESSIONS
       Duration expressions, which appear in the "set" command and various
       other parts of the API, are parsed by Time::Duration::Parse.  A
       duration is either a plain number, which is treated like a number of
       seconds, or a number and a string representing time units where the
       string is one of:

	   s second seconds sec secs
	   m minute minutes min mins
	   h hr hour hours
	   d day days
	   w week weeks
	   M month months
	   y year years

       e.g. the following are all valid duration expressions:

	   25
	   3s
	   5 seconds
	   1 minute and ten seconds
	   1 hour

KEY AND VALUE TRANSFORMATIONS
       CHI strives to accept arbitrary keys and values for caching regardless
       of the limitations of the underlying driver.

   Key transformations
       ·   Keys that are references are serialized - see "key_serializer".

       ·   Keys with wide (>255) characters are utf8 encoded.

       ·   Keys exceeding the maximum length for the underlying driver are
	   digested - see "max_key_length" and "key_digester".

       ·   For some drivers (e.g. CHI::Driver::File), keys containing special
	   characters or whitespace are escaped with URL-like escaping.

       Note: All transformations above with the exception of escaping are one-
       way, meaning that CHI does not attempt to undo them when returned from
       "get_keys"; and idempotent, meaning that applying them a second time
       has no effect. So when you call "get_keys", the key you get may not be
       exactly what you passed in, but you'll be able to pass that key in to
       get the corresponding object.

   Value transformations
       ·   Values which are references are automatically serialized before
	   storing, and deserialized after retrieving - see "serializer".

       ·   Values with their utf8 flag on are utf8 encoded before storing, and
	   utf8 decoded after retrieving.

SUBCACHES
       It is possible to a cache to have one or more subcaches. There are
       currently two types of subcaches: L1 and mirror.

   L1 cache
       An L1 (or "level one") cache sits in front of the primary cache,
       usually to provide faster access for commonly accessed cache entries.
       For example, this places an in-process Memory cache in front of a
       Memcached cache:

	   my $cache = CHI->new(
	       driver	=> 'Memcached',
	       servers	=> [ "10.0.0.15:11211", "10.0.0.15:11212" ],
	       l1_cache => { driver => 'Memory', global => 1, max_size => 1024*1024 }
	   );

       On a "get", the L1 cache is checked first - if a valid value exists, it
       is returned. Otherwise, the primary cache is checked - if a valid value
       exists, it is returned, and the value is placed in the L1 cache with
       the same expiration time. In this way, items fetched most frequently
       from the primary cache will tend to be in the L1 cache.

       "set" operations are distributed to both the primary and L1 cache.

       You can access the L1 cache with the "l1_cache" method. For example,
       this clears the L1 cache but leaves the primary cache intact:

	   $cache->l1_cache->clear();

   Mirror cache
       A mirror cache is a write-only cache that, over time, mirrors the
       content of the primary cache. "set" operations are distributed to both
       the primary and mirror cache, but "get" operations go only to the
       primary cache.

       Mirror caches are useful when you want to migrate from one cache to
       another.	 You can populate a mirror cache and switch over to it once it
       is sufficiently populated. For example, here we migrate from an old to
       a new cache directory:

	   my $cache = CHI->new(
	       driver	       => 'File',
	       root_dir	       => '/old/cache/root',
	       mirror_cache => { driver => 'File', root_dir => '/new/cache/root' },
	   );

       We leave this running for a few hours (or as needed), then replace it
       with

	   my $cache = CHI->new(
	       driver	=> 'File',
	       root_dir => '/new/cache/root'
	   );

       You can access the mirror cache with the "mirror_cache" method. For
       example, to see how many keys have made it over to the mirror cache:

	   my @keys = $cache->mirror_cache->get_keys();

   Creating subcaches
       As illustrated above, you create subcaches by passing the "l1_cache"
       and/or "mirror_cache" option to the CHI constructor. These options, in
       turn, should contain a hash of options to create the subcache with.

       The cache containing the subcache is called the parent cache.

       The following options are automatically inherited by the subcache from
       the parent cache, and may not be overridden:

	   expires_at
	   expires_in
	   expires_variance
	   serializer

       (Reason: for efficiency, we want to create a single cache object and
       store it in both caches. The cache object contains expiration
       information and is dependent on the serializer.	At some point we could
       conceivably add code that will use a single object or separate objects
       as necessary, and thus allow the above to be overridden.)

       The following options are automatically inherited by the subcache from
       the parent cache, but may be overridden:

	   namespace
	   on_get_error
	   on_set_error

       All other options are initialized in the subcache as normal,
       irrespective of their values in the parent.

       It is not currently possible to pass an existing cache in as a
       subcache.

   Common subcache behaviors
       These behaviors hold regardless of the type of subcache.

       The following methods are distributed to both the primary cache and
       subcache:

	   clear
	   expire
	   purge
	   remove

       The following methods return information solely from the primary cache.
       However, you are free to call them explicitly on the subcache. (Trying
       to merge in subcache information automatically would require too much
       guessing about the caller's intent.)

	   get_keys
	   get_namespaces
	   get_object
	   get_expires_at
	   exists_and_is_expired
	   is_valid
	   dump_as_hash

   Multiple subcaches
       It is valid for a cache to have one of each kind of subcache, e.g. an
       L1 cache and a mirror cache.

       A cache cannot have more than one of each kind of subcache, but a
       subcache can have its own subcaches, and so on. e.g.

	   my $cache = CHI->new(
	       driver	=> 'Memcached',
	       servers	=> [ "10.0.0.15:11211", "10.0.0.15:11212" ],
	       l1_cache => {
		   driver     => 'File',
		   root_dir   => '/path/to/root',
		   l1_cache   => { driver => 'RawMemory', global => 1 }
	       }
	   );

   Methods for parent caches
       has_subcaches( )
	   Returns a boolean indicating whether this cache has subcaches.

       l1_cache( )
	   Returns the L1 cache for this cache, if any. Can only be called if
	   has_subcaches is true.

       mirror_cache( )
	   Returns the mirror cache for this cache, if any. Can only be called
	   if has_subcaches is true.

       subcaches( )
	   Returns the subcaches for this cache, in arbitrary order. Can only
	   be called if has_subcaches is true.

   Methods for subcaches
       is_subcache( )
	   Returns a boolean indicating whether this is a subcache.

       subcache_type( )
	   Returns the type of subcache as a string, e.g. 'l1_cache' or
	   'mirror_cache'.  Can only be called if is_subcache is true.

       parent_cache( )
	   Returns the parent cache (weakened to prevent circular reference).
	   Can only be called if is_subcache is true.

   Developing new kinds of subcaches
       At this time, subcache behavior is hardcoded into CHI::Driver, so there
       is no easy way to modify the behavior of existing subcache types or
       create new ones.	 We'd like to make this more flexible eventually.

SIZE AWARENESS
       If "is_size_aware" or "max_size" are passed to the constructor, the
       cache will be size aware - that is, it will keep track of its own size
       (in bytes) as items are added and removed. You can get a cache's size
       with "get_size".

       Size aware caches generally keep track of their size in a separate
       meta-key, and have to do an extra store whenever the size changes (e.g.
       on each set and remove).

   Maximum size and discard policies
       If a cache's size rises above its "max_size", items are discarded until
       the cache size is sufficiently below the max size. (See
       "max_size_reduction_factor" for how to fine-tune this.)

       The order in which items are discarded is controlled with
       "discard_policy".  The default discard policy is 'arbitrary', which
       discards items in an arbitrary order.  The available policies and
       default policy can differ with each driver, e.g. the
       CHI::Driver::Memory driver provides and defaults to an 'LRU' policy.

   Appropriate drivers
       Size awareness was chiefly designed for, and works well with, the
       CHI::Driver::Memory driver: one often needs to enforce a maximum size
       on a memory cache, and the overhead of tracking size in memory is
       negligible.  However, the capability may be useful with other drivers.

       Some drivers - for example, CHI::Driver::FastMmap and
       CHI::Driver::Memcached - inherently keep track of their size and
       enforce a maximum size, and it makes no sense to turn on CHI's size
       awareness for these.

       Also, for drivers that cannot atomically read and update a value - for
       example, CHI::Driver::File - there is a race condition in the updating
       of size that can cause the size to grow inaccurate over time.

SUBCLASSING AND CONFIGURING CHI
       You can subclass CHI for your own application and configure it in a
       variety of ways, e.g. pre-defining storage types and defaults for new
       cache objects. Your configuration will be independent of the main CHI
       class and other CHI subclasses.

       Start with a trivial subclass:

	   package My::CHI;
	   use base qw(CHI);
	   1;

       Then, just use your subclass in place of CHI:

	   my $cache = My::CHI->new( ... );

	   print $cache->chi_root_class;
	      ==> 'My::CHI'

       This obviously doesn't change any behavior by itself. Here's an example
       with actual config:

	   package My::CHI;
	   use base qw(CHI);

	   __PACKAGE__->config({
	       storage	 => {
		   local_file => { driver => 'File', root_dir => '/my/root' },
		   memcached  => {
		       driver  => 'Memcached::libmemcached',
		       servers => [ '10.0.0.15:11211', '10.0.0.15:11212' ]
		   },
	       },
	       namespace => {
		   'Foo' => { storage => 'local_file' },
		   'Bar' => { storage => 'local_file', depth => 3 },
		   'Baz' => { storage => 'memcached' },
	       }
	       defaults	 => { storage => 'local_file' },
	       memoize_cache_objects => 1,
	   });

	   1;

       Each of these config keys is explained in the next section.

   Configuration keys
       storage
	   A map of names to parameter hashrefs. This provides a way to
	   encapsulate common sets of parameters that might be used in many
	   caches. e.g. if you define

	       storage => {
		   local_file => { driver => 'File', root_dir => '/my/root' },
		   ...
	       }

	   then

	       my $cache = My::CHI->new
		  (namespace => 'Foo', storage => 'local_file');

	   is equivalent to

	       my $cache = My::CHI->new
		  (namespace => 'Foo', driver => 'File', root_dir => '/my/root');

       namespace
	   A map of namespace names to parameter hashrefs. When you create a
	   cache object with the specified namespace, the hashref of
	   parameters will be applied as defaults. e.g. if you define

	       namespace => {
		   'Foo' => { driver => 'File', root_dir => '/my/root' },
		   'Bar' => { storage => 'database' },
		   ...
	       }

	   then

	       my $cache1 = My::CHI->new
		  (namespace => 'Foo');
	       my $cache2 = My::CHI->new
		  (namespace => 'Bar');

	   is equivalent to

	       my $cache1 = My::CHI->new
		  (namespace => 'Foo', driver => 'File', root_dir => '/my/root');
	       my $cache2 = My::CHI->new
		  (namespace => 'Bar', storage => 'database');

       defaults
	   A hash of parameters that will be used as core defaults for all
	   cache objects created under this root class. e.g.

	       defaults => {
		   on_get_error => 'die',
		   expires_variance => 0.2,
	       }

	   These can be overridden by namespace defaults, storage settings, or
	   "new" parameters.

       memoize_cache_objects
	   True or false, indicates whether "My::CHI->new" should memoize and
	   return the same cache object if given the same parameters. This can
	   speed things up if you create cache objects frequently. Will
	   currently only work for 0- or 1- key parameter hashes. e.g.

	       My::CHI->config({
		   memoize_cache_objects => 1,
	       });

	   then

	       # $cache1 and $cache2 will be the same object, regardless of what
	       # namespace and storage defaults are associated with 'Foo'
	       #
	       my $cache1 = My::CHI->new(namespace => 'Foo');
	       my $cache2 = My::CHI->new(namespace => 'Foo');

	       # $cache3 and $cache4 will be different objects
	       #
	       my $cache3 = My::CHI->new
		  (namespace => 'Bar', driver => 'File', root_dir => '/my/root');
	       my $cache4 = My::CHI->new
		  (namespace => 'Bar', driver => 'File', root_dir => '/my/root');

	   To clear the memoized cache objects, call

	       My::CHI->clear_memoized_cache_objects;

   How defaults are combined
       Defaults are applied in the following order, from highest to lowest
       precedence:

       ·   Parameters passed in "new"

       ·   Namespace defaults, if any

       ·   Storage settings, if any

       ·   Core defaults defined under 'defaults'

   Inheritance of config
       A subclass will automatically inherit the configuration of its parent
       if it does not call "config" itself (ala Class::Data::Inheritable).

   Reading config from a file
	   use YAML::XS qw(LoadFile);

	   __PACKAGE__->config(LoadFile("/path/to/cache.yml"));

AVAILABILITY OF DRIVERS
       The following drivers are currently available as part of this
       distribution:

       ·   CHI::Driver::Memory - In-process memory based cache

       ·   CHI::Driver::RawMemory - In-process memory based cache that stores
	   references directly instead of serializing/deep-copying

       ·   CHI::Driver::File - File-based cache using one file per entry in a
	   multi-level directory structure

       ·   CHI::Driver::FastMmap - Shared memory interprocess cache via
	   mmap'ed files

       ·   CHI::Driver::Null - Dummy cache in which nothing is stored

       ·   CHI::Driver::CacheCache - CHI wrapper for Cache::Cache

       The following drivers are currently available as separate CPAN
       distributions:

       ·   CHI::Driver::Memcached - Distributed memory-based cache (works with
	   Cache::Memcached, Cache::Memcached::Fast, and
	   Cache::Memcached::libmemcached)

       ·   CHI::Driver::DBI - Cache in any DBI-supported database

       ·   CHI::Driver::BerkeleyDB - Cache in BerkeleyDB files

       ·   CHI::Driver::Redis - Cache in Redis <http://redis.io/>

       This list is likely incomplete. A complete set of drivers can be found
       on CPAN by searching for "CHI::Driver".

PERFORMANCE COMPARISON OF DRIVERS
       See CHI::Benchmarks for a comparison of read/write times of both CHI
       and non-CHI cache implementations.

       "etc/bench/bench.pl" in the "CHI" distribution contains a script to run
       these types of benchmarks on your own system.

DEVELOPING NEW DRIVERS
       See CHI::Driver::Development for information on developing new drivers.

LOGGING
       "CHI" uses Log::Any for logging events. For example, a debug log
       message is sent for every cache get and set.

       See Log::Any documentation for how to control where logs get sent, if
       anywhere.

STATS
       CHI can record statistics, such as number of hits, misses and sets, on
       a per-namespace basis and log the results to your Log::Any logger.  You
       can then use utilities included with this distribution to read stats
       back from the logs and report a summary. See CHI::Stats for details.

RELATION TO OTHER MODULES
   Cache::Cache
       CHI is intended as an evolution of DeWitt Clinton's Cache::Cache
       package. It starts with the same basic API (which has proven durable
       over time) but addresses some implementation shortcomings that cannot
       be fixed in Cache::Cache due to backward compatibility concerns.	 In
       particular:

       Performance
	   Some of Cache::Cache's subclasses (e.g. Cache::FileCache) have been
	   justifiably criticized as inefficient. CHI has been designed from
	   the ground up with performance in mind, both in terms of general
	   overhead and in the built-in driver classes. Method calls are kept
	   to a minimum, data is only serialized when necessary, and metadata
	   such as expiration time is stored in packed binary format alongside
	   the data.

       Ease of subclassing
	   New Cache::Cache subclasses can be tedious to create, due to a lack
	   of code refactoring, the use of non-OO package subroutines, and the
	   separation of "cache" and "backend" classes. With CHI, the goal is
	   to make the creation of new drivers as easy as possible, roughly
	   the same as writing a TIE interface to your data store.  Concerns
	   like serialization and expiration options are handled by the driver
	   base class so that individual drivers don't have to worry about
	   them.

       Increased compatibility with cache implementations
	   Probably because of the reasons above, Cache::Cache subclasses were
	   never created for some of the most popular caches available on
	   CPAN, e.g.  Cache::FastMmap and Cache::Memcached.  CHI's goal is to
	   be able to support these and other caches with a minimum
	   performance overhead and minimum of glue code required.

   Cache
       The Cache distribution is another redesign and implementation of Cache,
       created by Chris Leishman in 2003. Like CHI, it improves performance
       and reduces the barrier to implementing new cache drivers. It breaks
       with the Cache::Cache interface in a few ways that I considered non-
       negotiable - for example, get/set do not serialize data, and namespaces
       are an optional feature that drivers may decide not to implement.

   Cache::Memcached, Cache::FastMmap, etc.
       CPAN sports a variety of full-featured standalone cache modules
       representing particular backends. CHI does not reinvent these but
       simply wraps them with an appropriate driver. For example,
       CHI::Driver::Memcached and CHI::Driver::FastMmap are thin layers around
       Cache::Memcached and Cache::FastMmap.

       Of course, because these modules already work on their own, there will
       be some overlap. Cache::FastMmap, for example, already has code to
       serialize data and handle expiration times. Here's how CHI resolves
       these overlaps.

       Serialization
	   CHI handles its own serialization, passing a flat binary string to
	   the underlying cache backend. The notable exception is
	   CHI::Driver::RawMemory which does no serialization.

       Expiration
	   CHI packs expiration times (as well as other metadata) inside the
	   binary string passed to the underlying cache backend. The backend
	   is unaware of these values; from its point of view the item has no
	   expiration time. Among other things, this means that you can use
	   CHI to examine expired items (e.g. with $cache->get_object) even if
	   this is not supported natively by the backend.

	   At some point CHI will provide the option of explicitly notifying
	   the backend of the expiration time as well. This might allow the
	   backend to do better storage management, etc., but would prevent
	   CHI from examining expired items.

       Naturally, using CHI's FastMmap or Memcached driver will never be as
       time or storage efficient as simply using Cache::FastMmap or
       Cache::Memcached.  In terms of performance, we've attempted to make the
       overhead as small as possible, on the order of 5% per get or set
       (benchmarks coming soon). In terms of storage size, CHI adds about 16
       bytes of metadata overhead to each item. How much this matters
       obviously depends on the typical size of items in your cache.

SUPPORT AND DOCUMENTATION
       Questions and feedback are welcome, and should be directed to the perl-
       cache mailing list:

	   http://groups.google.com/group/perl-cache-discuss

       Bugs and feature requests will be tracked at RT:

	   http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI
	   bug-chi@rt.cpan.org

       The latest source code can be browsed and fetched at:

	   http://github.com/jonswar/perl-chi/tree/master
	   git clone git://github.com/jonswar/perl-chi.git

ACKNOWLEDGMENTS
       Thanks to Dewitt Clinton for the original Cache::Cache, to Rob Mueller
       for the Perl cache benchmarks, and to Perrin Harkins for the
       discussions that got this going.

       CHI was originally designed and developed for the Digital Media group
       of the Hearst Corporation, a diversified media company based in New
       York City.  Many thanks to Hearst management for agreeing to this open
       source release.

SEE ALSO
       Cache::Cache

AUTHOR
       Jonathan Swartz <swartz@pobox.com>

COPYRIGHT AND LICENSE
       This software is copyright (c) 2011 by Jonathan Swartz.

       This is free software; you can redistribute it and/or modify it under
       the same terms as the Perl 5 programming language system itself.

perl v5.14.2			  2012-07-04				CHI(3)
[top]

List of man pages available for Fedora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net