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

pymor.core.cache.NoneType[source]
pymor.core.cache.cache_regions[source]
class pymor.core.cache.CacheRegion[source]

Base class for all pyMOR cache regions.

persistent[source]

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(self)[source]

Clear the entire cache region.

abstract get(self, key)[source]

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(self, key, value)[source]

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[source]

Bases: pymor.core.base.ImmutableObject

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

cache_region[source]

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[source]

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.

cached_method_call(self, method, *args, **kwargs)[source]

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(self)[source]

Disable caching for this instance.

enable_caching(self, region, cache_id=None)[source]

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.

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

Bases: CacheRegion

Base class for all pyMOR cache regions.

persistent[source]

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(self)[source]

Clear the entire cache region.

get(self, key)[source]

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(self, key, value)[source]

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)[source]

Bases: CacheRegion

Base class for all pyMOR cache regions.

persistent[source]

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[source]
clear(self)[source]

Clear the entire cache region.

get(self, key)[source]

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(self, key, value)[source]

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)[source]
pymor.core.cache.cached(function)[source]

Decorator to make a method of CacheableObject actually cached.

pymor.core.cache.cleanup_non_persistent_regions()[source]
pymor.core.cache.clear_caches()[source]

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)[source]
pymor.core.cache.disable_caching()[source]

Globally disable caching.

pymor.core.cache.enable_caching()[source]

Globally enable caching.