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:
the instance’s
cache_id
in case of apersistent
CacheRegion
, else the instance’suid
,the method’s
__name__
,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:
Calling
disable_caching
(enable_caching
), to disable (enable) caching globally.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[source]¶
Base class for all pyMOR cache regions.
Methods
Clear the entire cache region.
Return cache entry for given key.
Set cache entry for
key
to givenvalue
.
- 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 thecache_regions
dict. IfNone
or'none'
, caching is disabled.
Methods
Call a given
method
and cache the return value.Disable caching for this instance.
Enable caching for this instance.
- cached_method_call(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)
.
- enable_caching(region, cache_id=None)[source]¶
Enable caching for this instance.
Warning
Note that using
with_
will resetcache_region
andcache_id
to their class defaults.Parameters
- region
Name of the
CacheRegion
to use. Must correspond to a key in thecache_regions
dict. IfNone
or'none'
, caching is disabled.- cache_id
Identifier for the object instance on which a cached method is called. Must be specified when
region
ispersistent
. Whenregion
is notpersistent
and nocache_id
is given, the object’suid
is used instead.
- class pymor.core.cache.DiskRegion(path, max_size, persistent)[source]¶
Bases:
CacheRegion
Base class for all pyMOR cache regions.
Methods
Clear the entire cache region.
Return cache entry for given key.
Set cache entry for
key
to givenvalue
.
- class pymor.core.cache.MemoryRegion(max_keys)[source]¶
Bases:
CacheRegion
Base class for all pyMOR cache regions.
Methods
Clear the entire cache region.
Return cache entry for given key.
Set cache entry for
key
to givenvalue
.
- pymor.core.cache.cached(function)[source]¶
Decorator to make a method of
CacheableObject
actually cached.