<<

NAME

Koha::Cache - Handling caching of html and Objects for Koha

SYNOPSIS

  use Koha::Cache;
  my $cache = Koha::Cache->new({cache_type => $cache_type, %params});

DESCRIPTION

Koha caching routines. This class provides two interfaces for cache access. The first, traditional OO interface provides the following functions:

FUNCTIONS

get_instance

    my $cache = Koha::Cache->get_instance();

This gets a shared instance of the cache, set up in a very default way. This is the recommended way to fetch a cache object. If possible, it'll be persistent across multiple instances.

new

Create a new Koha::Cache object. This is required for all cache-related functionality.

is_cache_active

Routine that checks whether or not a default caching method is active on this object.

set_in_cache

    $cache->set_in_cache($key, $value, [$options]);

Save a value to the specified key in the cache. A hashref of options may be specified.

The possible options are:

expiry

Expiry time of this cached entry in seconds.

unsafe

If set, this will avoid performing a deep copy of the item. This means that it won't be safe if something later modifies the result of the function. It should be used with caution, and could save processing time in some situations where is safe to use it.

cache

The cache object to use if you want to provide your own. It should be an instance of Cache::* and follow the same interface as Cache::Memcache.

get_from_cache

    my $value = $cache->get_from_cache($key, [ $options ]);

Retrieve the value stored under the specified key in the default cache.

The possible options are:

unsafe

If set, this will avoid performing a deep copy of the item. This means that it won't be safe if something later modifies the result of the function. It should be used with caution, and could save processing time in some situations where is safe to use it. Make sure you know what you are doing!

cache

The cache object to use if you want to provide your own. It should be an instance of Cache::* and follow the same interface as Cache::Memcache.

clear_from_cache

    $cache->clear_from_cache($key);

Remove the value identified by the specified key from the default cache.

flush_all

    $cache->flush_all();

Clear the entire default cache.

TIED INTERFACE

Koha::Cache also provides a tied interface which enables users to provide a constructor closure and (after creation) treat cached data like normal reference variables and rely on the cache Just Working and getting updated when it expires, etc.

    my $cache = Koha::Cache->new();
    my $data = 'whatever';
    my $scalar = Koha::Cache->create_scalar(
        {
            'key'         => 'whatever',
            'timeout'     => 2,
            'constructor' => sub { return $data; },
        }
    );
    print "$$scalar\n"; # Prints "whatever"
    $data = 'somethingelse';
    print "$$scalar\n"; # Prints "whatever" because it is cached
    sleep 2; # Wait until the cache entry has expired
    print "$$scalar\n"; # Prints "somethingelse"

    my $hash = Koha::Cache->create_hash(
        {
            'key'         => 'whatever',
            'timeout'     => 2,
            'constructor' => sub { return $data; },
        }
    );
    print "$$variable\n"; # Prints "whatever"

The gotcha with this interface, of course, is that the variable returned by create_scalar and create_hash is a reference to a tied variable and not a tied variable itself.

The tied variable is configured by means of a hashref passed in to the create_scalar and create_hash methods. The following parameters are supported:

key

Required. The key to use for identifying the variable in the cache.

constructor

Required. A closure (or reference to a function) that will return the value that needs to be stored in the cache.

preload

Optional. A closure (or reference to a function) that gets run to initialize the cache when creating the tied variable.

arguments

Optional. Array reference with the arguments that should be passed to the constructor function.

timeout

Optional. The cache timeout in seconds for the variable. Defaults to 600 (ten minutes).

cache_type

Optional. Which type of cache to use for the variable. Defaults to whatever is set in the environment variable CACHING_SYSTEM. If set to 'null', disables caching for the tied variable.

allowupdate

Optional. Boolean flag to allow the variable to be updated directly. When this is set and the variable is used as an l-value, the cache will be updated immediately with the new value. Using this is probably a bad idea on a multi-threaded system. When allowupdate is not set to true, using the tied variable as an l-value will have no effect.

destructor

Optional. A closure (or reference to a function) that should be called when the tied variable is destroyed.

unset

Optional. Boolean flag to tell the object to remove the variable from the cache when it is destroyed or goes out of scope.

inprocess

Optional. Boolean flag to tell the object not to refresh the variable from the cache every time the value is desired, but rather only when the local copy of the variable is older than the timeout.

create_scalar

    my $scalar = Koha::Cache->create_scalar(\%params);

Create scalar tied to the cache.

EXPORT

None by default.

SEE ALSO

Koha::Cache::Object

AUTHOR

Chris Cormack, <chris@bigballofwax.co.nz> Paul Poulain, <paul.poulain@biblibre.com> Jared Camins-Esakov, <jcamins@cpbibliography.com>

<<