Package pyxmpp :: Module cache :: Class CacheSuite
[hide private]

Class CacheSuite

source code

Caching proxy for object retrieval and caching.

Object factories for other classes 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.

Objects are addressed using their class and a class dependant address. Eg. pyxmpp.jabber.disco.DiscoInfo objects are addressed using (pyxmpp.jabber.disco.DiscoInfo,(jid, node)) tuple.

Additionaly 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:

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, object_class, address, state, object_handler, error_handler=None, timeout_handler=None, backup_state=None, timeout=None, freshness_period=None, expiration_period=None, purge_period=None)
Request an object of given class, with given address and state not worse than state.
source code
 
tick(self)
Do the regular cache maintenance.
source code
 
register_fetcher(self, object_class, fetcher_class)
Register a fetcher class for an object class.
source code
 
unregister_fetcher(self, object_class)
Unregister a fetcher class for an object class.
source code
Instance Variables [hide private]
: dict of (classobj, addr) -> Cache _caches
: dictionary of per-class caches.
: 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 obejects of one class 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, object_class, address, state, object_handler, error_handler=None, timeout_handler=None, backup_state=None, timeout=None, freshness_period=None, expiration_period=None, purge_period=None)

source code 
Request an object of given class, 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:
  • object_class (: classobj) - : class (type) of the object requested.
  • 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.

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.

register_fetcher(self, object_class, fetcher_class)

source code 
Register a fetcher class for an object class.
Parameters:
  • object_class (: classobj) - : class to be retrieved by the fetcher.
  • fetcher_class (: CacheFetcher based class) - : the fetcher class.

unregister_fetcher(self, object_class)

source code 
Unregister a fetcher class for an object class.
Parameters:
  • object_class (: classobj) - : class retrieved by the fetcher.

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