Package pyxmpp :: Module cache :: Class Cache
[show private | hide private]
[frames | no frames]

Class Cache


Caching proxy for object retrieval and caching.

Object factories ("fetchers") are registered in the Cache object and used to e.g. retrieve requested objects from network. They are called only when the requested object is not in the cache or is not fresh enough.

A state (freshness level) name may be provided when requesting an object. When the cached item state is "less fresh" then requested, then new object will be retrieved.

Following states are defined:


Method Summary
  __init__(self, max_items, default_freshness_period, default_expiration_period, default_purge_period)
Initialize a Cache object.
str add_item(self, item)
Add an item to the cache.
CacheItem get_item(self, address, state)
Get an item from the cache.
  invalidate_object(self, address, state)
Force cache item state change (to 'worse' state only).
int num_items(self)
Get the number of items in the cache.
  purge_items(self)
Remove purged and overlimit items from the cache.
  remove_fetcher(self, fetcher)
Remove a running fetcher from the list of active fetchers.
  request_object(self, address, state, object_handler, error_handler, timeout_handler, backup_state, timeout, freshness_period, expiration_period, purge_period)
Request an object with given address and state not worse than state.
  set_fetcher(self, fetcher_class)
Set the fetcher class.
  tick(self)
Do the regular cache maintenance.
str update_item(self, item)
Update state of an item in the cache.

Instance Variable Summary
timedelta default_expiration_period: default expiration period (in seconds).
timedelta default_freshness_period: default freshness period (in seconds).
timedelta default_purge_period: default purge period (in seconds).
int max_items: maximum number of items to store.
list of (int, CacheFetcher) _active_fetchers: list of active fetchers sorted by the time of its expiration time.
CacheFetcher based class _fetcher: fetcher class for this cache.
dict of (classobj, addr) -> CacheItem _items: dictionary of stored items.
list of (int, datetime, CacheItem) _items_list: list of stored items with the most suitable for purging first.
threading.RLock _lock: lock for thread safety.

Method Details

__init__(self, max_items, default_freshness_period=datetime.timedelta(0, 3600), default_expiration_period=datetime.timedelta(0, 43200), default_purge_period=datetime.timedelta(1))
(Constructor)

Initialize a Cache object.
Parameters:
max_items - maximum number of items to store.
           (type=number)
default_freshness_period - default freshness period (in seconds).
           (type=number)
default_expiration_period - default expiration period (in seconds).
           (type=number)
default_purge_period - default purge period (in seconds). When 0 then items are never purged because of their age.
           (type=number)

add_item(self, item)

Add an item to the cache.

Item state is updated before adding it (it will not be 'new' any more).

Parameters:
item - the item to add.
           (type=CacheItem)
Returns:
state of the item after addition.
           (type=str)

get_item(self, address, state='fresh')

Get an item from the cache.
Parameters:
address - its address.
           (type=any hashable)
state - the worst state that is acceptable.
           (type=str)
Returns:
the item or None if it was not found.
           (type=CacheItem)

invalidate_object(self, address, state='stale')

Force cache item state change (to 'worse' state only).
Parameters:
state - the new state requested.
           (type=str)

num_items(self)

Get the number of items in the cache.
Returns:
number of items.
           (type=int)

purge_items(self)

Remove purged and overlimit items from the cache.

TODO: optimize somehow.

Leave no more than 75% of self.max_items items in the cache.

remove_fetcher(self, fetcher)

Remove a running fetcher from the list of active fetchers.
Parameters:
fetcher - fetcher instance.
           (type=CacheFetcher)

request_object(self, address, state, object_handler, error_handler=None, timeout_handler=None, backup_state=None, timeout=datetime.timedelta(0, 3600), freshness_period=None, expiration_period=None, purge_period=None)

Request an object with given address and state not worse than state. The object will be taken from cache if available, and created/fetched otherwise. The request is asynchronous -- this metod doesn't return the object directly, but the object_handler is called as soon as the object is available (this may be before request_object returns and may happen in other thread). On error the error_handler will be called, and on timeout -- the timeout_handler.
Parameters:
address - address of the object requested.
           (type=any hashable)
state - the worst acceptable object state. When 'new' then always a new object will be created/fetched. 'stale' will select any item available in cache.
           (type="new", "fresh", "old" or "stale")
object_handler - function to be called when object is available. It will be called with the following arguments: address, object and its state.
           (type=callable(address, value, state))
error_handler - function to be called on object retrieval error. It will be called with two arguments: requested address and additional error information (fetcher-specific, may be StanzaError for XMPP objects). If not given, then the object handler will be called with object set to None and state "error".
           (type=callable(address, error_data))
timeout_handler - function to be called on object retrieval timeout. It will be called with only one argument: the requested address. If not given, then the error_handler will be called instead, with error details set to None.
           (type=callable(address))
backup_state - when set and object in state state is not available in the cache and object retrieval failed then object with this state will also be looked-up in the cache and provided if available.
           (type="new", "fresh", "old" or "stale")
timeout - time interval after which retrieval of the object should be given up.
           (type=timedelta)
freshness_period - time interval after which the item created should become 'old'.
           (type=timedelta)
expiration_period - time interval after which the item created should become 'stale'.
           (type=timedelta)
purge_period - time interval after which the item created shuld be removed from the cache.
           (type=timedelta)

set_fetcher(self, fetcher_class)

Set the fetcher class.
Parameters:
fetcher_class - the fetcher class.
           (type=CacheFetcher based class)

tick(self)

Do the regular cache maintenance.

Must be called from time to time for timeouts and cache old items purging to work.

update_item(self, item)

Update state of an item in the cache.

Update item's state and remove the item from the cache if its new state is 'purged'

Parameters:
item - item to update.
           (type=CacheItem)
Returns:
new state of the item.
           (type=str)

Instance Variable Details

default_expiration_period

default expiration period (in seconds).
Type:
timedelta

default_freshness_period

default freshness period (in seconds).
Type:
timedelta

default_purge_period

default purge period (in seconds). When 0 then items are never purged because of their age.
Type:
timedelta

max_items

maximum number of items to store.
Type:
int

_active_fetchers

list of active fetchers sorted by the time of its expiration time.
Type:
list of (int, CacheFetcher)

_fetcher

fetcher class for this cache.
Type:
CacheFetcher based class

_items

dictionary of stored items.
Type:
dict of (classobj, addr) -> CacheItem

_items_list

list of stored items with the most suitable for purging first.
Type:
list of (int, datetime, CacheItem)

_lock

lock for thread safety.
Type:
threading.RLock