pymor.core.cache

This module provides the caching facilities of pyMOR.

Any class that wishes to provide cached method calls should derive from CacheableObject. Methods which are to be cached can then be marked using the cached decorator.

To ensure consistency, CacheableObject derives from ImmutableObject: The return value of a cached method call should only depend on its arguments as well as the immutable state of the class instance.

Making this assumption, the keys for cache lookup are created from the following data:

1. the instance’s cache_id in case of a persistent CacheRegion, else the instance’s uid,

2. the method’s __name__,

3. the method’s arguments.

Note that instances of ImmutableObject are allowed to have mutable private attributes. It is the implementors responsibility not to break things. (See this warning.)

Backends for storage of cached return values derive from CacheRegion. Currently two backends are provided for memory-based and disk-based caching (MemoryRegion and DiskRegion). The available regions are stored in the module level cache_regions dict. The user can add additional regions (e.g. multiple disk cache regions) as required. CacheableObject.cache_region specifies a key of the cache_regions dict to select a cache region which should be used by the instance. (Setting cache_region to None or 'none' disables caching.)

By default, a ‘memory’, a ‘disk’ and a ‘persistent’ cache region are configured. The paths and maximum sizes of the disk regions, as well as the maximum number of keys of the memory cache region can be configured via the pymor.core.cache.default_regions.disk_path, pymor.core.cache.default_regions.disk_max_size, pymor.core.cache.default_regions.persistent_path, pymor.core.cache.default_regions.persistent_max_size and pymor.core.cache.default_regions.memory_max_keys defaults.

There two ways to disable and enable caching in pyMOR:

1. Calling disable_caching (enable_caching), to disable (enable) caching globally.

2. Calling CacheableObject.disable_caching (CacheableObject.enable_caching) to disable (enable) caching for a given instance.

Caching of a method is only active if caching has been enabled both globally (enabled by default) and on instance level. For debugging purposes, it is moreover possible to set the environment variable PYMOR_CACHE_DISABLE=1 which overrides any call to enable_caching.

A cache region can be emptied using CacheRegion.clear. The function clear_caches clears each cache region registered in cache_regions.

Module Contents

class pymor.core.cache.CacheRegion

Base class for all pyMOR cache regions.

persistent

If True, cache entries are kept between multiple program runs.

Methods

clear	Clear the entire cache region.
get	Return cache entry for given key.
set	Set cache entry for key to given value.

abstract clear()

Clear the entire cache region.

abstract get(key)

Return cache entry for given key.

Parameters

key

The key for the cache entry.

Returns

(True, entry)

in case the key has been found in the cache region.

(False, None)

in case the key is not present in the cache region.

abstract set(key, value)

Set cache entry for key to given value.

This method is usually called only once for any given key (with the exemption of issues due to concurrency).

class pymor.core.cache.CacheableObject

Bases: pymor.core.base.ImmutableObject

Base class for anything that wants to use our built-in caching.

cache_region

Name of the CacheRegion to use. Must correspond to a key in the cache_regions dict. If None or 'none', caching is disabled.

cache_id

Identifier for the object instance on which a cached method is called.

Methods

cached_method_call	Call a given method and cache the return value.
disable_caching	Disable caching for this instance.
enable_caching	Enable caching for this instance.
get_cached_value	Retrieve value from cache.
set_cached_value	Store value in active CacheRegion.

cached_method_call(method, *args, **kwargs)

Call a given method and cache the return value.

This method can be used as an alternative to the cached decorator.

Parameters

method

The method that is to be called. This has to be a method of self.

args

Positional arguments for method.

kwargs

Keyword arguments for method

Returns

The (possibly cached) return value of method(*args, **kwargs).

disable_caching()

Disable caching for this instance.

enable_caching(region, cache_id=None)

Enable caching for this instance.

Warning

Note that using with_ will reset cache_region and cache_id to their class defaults.

Parameters

region

Name of the CacheRegion to use. Must correspond to a key in the cache_regions dict. If None or 'none', caching is disabled.

cache_id

Identifier for the object instance on which a cached method is called. Must be specified when region is persistent. When region is not persistent and no cache_id is given, the object’s uid is used instead.

get_cached_value(key_data, value_factory=None)

Retrieve value from cache.

This low-level method allows retrieving cached values for pairs (self, key_data) from the object’s active CacheRegion.

If the corresponding value is not found in the cache, value_factory is called to compute the value. The value is then stored in the CacheRegion and returned. If value_factory is None, a KeyError is raised.

In most cases, the cached decorator should be used instead.

Parameters

key_data

The data/parameters from which the cache key is computed that is used to retrieve the value.

value_factory

A callable with no parameters that computes the desired value in case of a cache miss.

Returns

The cached value corresponding to the pair (self, key).

set_cached_value(key_data, value)

Store value in active CacheRegion.

This low-level method allows storing values for pairs (self, key) in the object’s active CacheRegion for later retrieval.

In most cases, the cached decorator should be used instead.

Parameters

key_data

The data/parameters from which the cache key is computed that is used to store the value.

value

Value to be stored.

class pymor.core.cache.DiskRegion(path, max_size, persistent)

Bases: CacheRegion

Base class for all pyMOR cache regions.

persistent

If True, cache entries are kept between multiple program runs.

Methods

clear	Clear the entire cache region.
get	Return cache entry for given key.
set	Set cache entry for key to given value.

clear()

Clear the entire cache region.

get(key)

Return cache entry for given key.

Parameters

key

The key for the cache entry.

Returns

(True, entry)

in case the key has been found in the cache region.

(False, None)

in case the key is not present in the cache region.

set(key, value)

Set cache entry for key to given value.

This method is usually called only once for any given key (with the exemption of issues due to concurrency).

class pymor.core.cache.MemoryRegion(max_keys)

Bases: CacheRegion

Base class for all pyMOR cache regions.

persistent

If True, cache entries are kept between multiple program runs.

Methods

clear	Clear the entire cache region.
get	Return cache entry for given key.
set	Set cache entry for key to given value.

NO_VALUE

clear()

Clear the entire cache region.

get(key)

Return cache entry for given key.

Parameters

key

The key for the cache entry.

Returns

(True, entry)

in case the key has been found in the cache region.

(False, None)

in case the key is not present in the cache region.

set(key, value)

Set cache entry for key to given value.

This method is usually called only once for any given key (with the exemption of issues due to concurrency).

pymor.core.cache.build_cache_key(obj)

pymor.core.cache.cached(function)

Decorator to make a method of CacheableObject actually cached.

pymor.core.cache.cleanup_non_persistent_regions()

pymor.core.cache.clear_caches()

Clear all cache regions.

pymor.core.cache.default_regions(disk_path=os.path.join(tempfile.gettempdir(), 'pymor.cache.' + getpass.getuser()), disk_max_size=1024**3, persistent_path=os.path.join(tempfile.gettempdir(), 'pymor.persistent.cache.' + getpass.getuser()), persistent_max_size=1024**3, memory_max_keys=1000)

pymor.core.cache.disable_caching()

Globally disable caching.

pymor.core.cache.enable_caching()

Globally enable caching.

pymor.core.cache.print_cached_methods()

pymor.core.cache.NoneType

pymor.core.cache.cache_regions