NAME

XAO::Cache - generic interface for caching various data

SYNOPSIS

my $cache=XAO::Cache->new(
    retrieve           => &real_retrieve,
    coords             => [qw(outer inner)],
    size               => 100,
    expire             => 30*60,
    backend            => 'Cache::Memory',
);

my $d1=$cache->get(outer => 123, inner => 'foo');

my $d2=$cache->get($self, outer => 234, extra => 'bar');

DESCRIPTION

NOTE: It is almost always better to use Config::cache() method instead of creating a cache directly with its new() method. That will also save on the initialization step - cache object themselves are cached and reused in that case.

XAO::Cache is a generic cache implementation for caching various "slow" data such as database content, results of remote requests and so on.

There is no operation of storing data into the cache. Instead cache is provided with a method to retrieve requested content whenever required. On subsequent calls a cached value would be returned until either expiration time is elapsed or cache has overgrown its maximum size. In which case the real query will be made again to actually retrieve data.

That means that cache always returns valid data or throws an error if that is not possible.

To force the cache to use "retrieve" to get a new value that is stored in the cache give an extra "force_update" parameter to the get() method.

METHODS

Here is the alphabetically arranged list of methods:

drop ($%)

Removes an element from cache. Useful to make cache aware of changes in the cached element -- when cached data are no longer valid.

Arguments must contain a list of coordinates the same as in get() method.

drop_all ($)

Remove all elements from the cache.

get ($%)

Retrieve a data element from the cache. The cache can decide to use real 'retrieve' method to get the data or return previously stored value instead.

All arguments given to the get() method will be passed to 'retrieve' method. As a special case if retrieve is a method of some class then a reference to object of that class must be the first argument followed by a hash with arguments.

Example of calling 'retrieve' as a function:

$cache->get(foo => 123, bar => 234);

Example of calling 'retrieve' as a method:

$cache->get($object, foo => 123, bar => 123);

Example of forcing an update of cache value:

$cache->get(foo => 123, bar => 234, force_update => 1);

new (%)

Creates a new independent instance of a cache. When that instance is destroyed all cache content is destroyed as well. Arguments are:

backend

Type of backend that will actuall keep values in cache. Can be either a XAO object name or an object reference.

Default is 'Cache::Memory' (XAO::DO::Cache::Memory).

coords

Coordinates of a data element in the cache -- reference to an array that keeps names of arguments identifying a data element in the cache. The order of elements in the list is significant -- first element is mandatory, the rest is optional.

A combination of all coordinates must uniquely identify a cached data element among all others in the cache. For instance, if you create a cache with customers, then 'customer_id' will most probably be your only coordinate. But if to retrieve a data element you need element type and id then your coordinates will be:

coords => ['type', 'id']

There is no default for coordinates.

Note: Coordinates are supposed to be text strings meeting isprint() criteria.

expire

Expiration time for data elements in the cache. Default is no expiration time.

retrieve

Reference to a method or a subroutine that will actually retrieve data element when there is no element in the cache or cache element has expired.

The subroutine gets all parameters passed to cache's get() method.

Cache does not perform any checks for correctness of result, so if for some reason retrieval cannot be performed an error should be thrown instead of returning undef or other indicator of failure.

size

Optional maximum size of the cache in Kbytes. If not specified then only expiration time will be used as a criteria to throw a data element out of cache.

value_maxlength

Maximum length of an individual value to be stored. Values longer than this size may be ignored by the cache, but it is still safe to return then from the retrieve() method. They MAY just not be cached.

Primarily this is useful for memcached configuration to match what the memcached server is going to reject anyway.

If there is a current project and that project Config object holds a /cache/config data then that data is used for default values, providing a way to, for instance, change cache backend globally for all project caches.

The configuration is structured like this:

cache => {
    config => {
        common => {
            backend => 'Cache::Memcached',
        },
        foo_cache => {
            backend => 'Cache::Memory',
            size    => 1_000_000,
        },
    },
},

For a cache named foo_cache the backend would be 'Cache::Memory' and for all other caches -- 'Cache::Memcached' in that case.

AUTHORS

Copyright (c) 2013 Andrew Maltsev <am@ejelta.com>. Copyright (c) 2002 XAO Inc., Andrew Maltsev <am@xao.com>.

SEE ALSO

Have a look at: XAO::DO::Cache::Memcached, XAO::DO::Cache::Memory, XAO::Objects, XAO::Base, XAO::FS, XAO::Web.