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:

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.

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)

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 labeled 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. Has no effect if $key does not exist in the cache.

Returns true if $key was in the cache, false otherwise.

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.

Does not modify expiration or other metadata. If $key exists but is expired, it will remain expired.

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

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

    is_empty

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.

L1 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

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

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

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

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

Maximum size and discard policies

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

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.

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

• Parameters passed in "new"
• Namespace defaults, if any
• Storage settings, if any
• Core defaults defined under 'defaults'

Inheritance of config

Reading config from a file

    use YAML::XS qw(LoadFile);

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

Cache::Cache

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

Cache::Memcached, Cache::FastMmap, etc.

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.