Package pyxmpp :: Module cache :: Class Cache

[hide private]

# Class Cache

source code

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:

> - 'new': always a new object should be retrieved.
> - 'fresh': a fresh object (not older than freshness time)
> - 'old': object not fresh, but most probably still valid.
> - 'stale': object known to be expired.

Instance Methods | [hide private]

__init__(self, max_items, default_freshness_period=datetime.timedelta(0, 3600), default_expiration_period=datetime.timedelta(0, 43200), default_purge_period=datetime.timedelta(1)) Initialize a Cache object. | source code

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`. | source code

invalidate_object(self, address, state=`'``stale``'`) Force cache item state change (to 'worse' state only). | source code

`str`

add_item(self, item) Add an item to the cache. | source code

CacheItem

get_item(self, address, state=`'``fresh``'`) Get an item from the cache. | source code

`str`

update_item(self, item) Update state of an item in the cache. | source code

`int`

num_items(self) Get the number of items in the cache. | source code

purge_items(self) Remove purged and overlimit items from the cache. | source code

tick(self) Do the regular cache maintenance. | source code

remove_fetcher(self, fetcher) Remove a running fetcher from the list of active fetchers. | source code

set_fetcher(self, fetcher_class) Set the fetcher class. | source code

Instance Variables | [hide private]

: `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.
: 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.

Method Details | [hide private]

### __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)

source code

Initialize a Cache object.

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

### 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)

source code

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` (: any hashable) - : address of the object requested.
  - `state` (: "new", "fresh", "old" or "stale") - : the worst acceptable object state. When 'new' then always a new object will be created/fetched. 'stale' will select any item available in cache.
  - `object_handler` (: callable(address, value, state)) - : function to be called when object is available. It will be called with the following arguments: address, object and its state.
  - `error_handler` (: callable(address, error_data)) - : 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".
  - `timeout_handler` (: callable(address)) - : 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`.
  - `backup_state` (: "new", "fresh", "old" or "stale") - : 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.
  - `timeout` (: timedelta) - : time interval after which retrieval of the object should be given up.
  - `freshness_period` (: timedelta) - : time interval after which the item created should become 'old'.
  - `expiration_period` (: timedelta) - : time interval after which the item created should become 'stale'.
  - `purge_period` (: timedelta) - : time interval after which the item created shuld be removed from the cache.

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

source code

Force cache item state change (to 'worse' state only).

Parameters:
  - `state` (: `str`) - : the new state requested.

### add_item(self, item)

source code

Add an item to the cache.

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

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

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

source code

Get an item from the cache.

Parameters:
  - `address` (: any hashable) - : its address.
  - `state` (: `str`) - : the worst state that is acceptable.
Returns: CacheItem
  the item or `None` if it was not found.

### update_item(self, item)

source code

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` (: CacheItem) - : item to update.
Returns: `str`
  new state of the item.

### num_items(self)

source code

Get the number of items in the cache.

Returns: `int`
  number of items.

### purge_items(self)

source code

Remove purged and overlimit items from the cache.

TODO: optimize somehow.

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

### tick(self)

source code

Do the regular cache maintenance.

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

### remove_fetcher(self, fetcher)

source code

Remove a running fetcher from the list of active fetchers.

Parameters:
  - `fetcher` (: CacheFetcher) - : fetcher instance.

### set_fetcher(self, fetcher_class)

source code

Set the fetcher class.

Parameters:
  - `fetcher_class` (: CacheFetcher based class) - : the fetcher class.

Instance Variable Details | [hide private]

### default_purge_period

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

Type:
  : timedelta