pyzim.cache.TopAccessCache

class documentation

class TopAccessCache(BaseCache):

Constructor: TopAccessCache(on_leave, max_size)

A BaseCache implementation that caches by most accessed.

This cache uses a double-linked list and two dictionaries. The list serves as the actual cache, keeping track of all elements. A dictionary maps the keys to the list segments, allowing O(1) access. Whenever get() or push() is called, a value is incremented in a dictionary. If the value exceeds the value of the tail and the element is not yet cached, the tail is replaced. If the value is already cached, the list segment may be pulled forward towards the head. Of course, whenever there is still space within the cache it will also be added to the cache regardless of access count.

Method	`__init__`	The default constructor.
Method	`clear`	Empty this cache.
Method	`get`	Return the element that has been cached for this key.
Method	`has`	Return True if an element is cached for the specific key.
Method	`push`	Push an element for this key into this cache.
Method	`remove`	If an element is cached for key, remove it from the cache.
Instance Variable	`lock`	thread-safety lock
Instance Variable	`max_size`	max number of elements to cache
Method	`_increment_access_counter`	Increment the number of times an element has been accessed.
Method	`_replace_tail_if_necessary`	If there is yet no value for the key cached but the access count is higher than tail, add this value to the cache.
Instance Variable	`_key2le`	Undocumented
Instance Variable	`_list`	Undocumented
Instance Variable	`_num_accesses`	Undocumented

Inherited from BaseCache:

Instance Variable on_leave a callable expecting two arguments (key, value) that will be called when an element leaves the cache

def __init__(self, on_leave=None, max_size=8): ¶

overrides pyzim.cache.BaseCache.__init__

The default constructor.

Parameters
on_leave:callable or `None`	See `BaseCache.__init__`
max_size:`int`	max number of elements to cache

def clear(self, call_on_leave=True): ¶

overrides pyzim.cache.BaseCache.clear

Empty this cache.

Parameters
call_on_leave:`bool`	if nonzero (default), call `BaseCache.on_leave` for each element cleared

def get(self, key): ¶

overrides pyzim.cache.BaseCache.get

Return the element that has been cached for this key.

Parameters
key:hashable	key for the element that should be returned

Returns
same as passed to `BaseCache.push`	the element

Raises
`KeyError`	if no element was cached for this key

def has(self, key): ¶

overrides pyzim.cache.BaseCache.has

Return True if an element is cached for the specific key.

Parameters
key:hashable	key of element that should be checked

Returns
`bool`	True if an element has been cached for this key

def push(self, key, element, allow_replacement=True): ¶

overrides pyzim.cache.BaseCache.push

Push an element for this key into this cache.

It is up for the cache to decide whether the element will actually be cached or not. If allow_replacement=False is set, no other element should be kicked from the cache.

Re-pushing an already cached element will not update the cached element.

Parameters
key:hashable	key which will be used to identify the element
element:any	element to cache
allow_replacement:`bool`	if this value is false, do not cache if this would kick another element from the cache

Returns
`bool`	True if the element is now cached, False otherwise

def remove(self, key, call_on_leave=True): ¶

overrides pyzim.cache.BaseCache.remove

If an element is cached for key, remove it from the cache.

Parameters
key:hashable	key of element to remove
call_on_leave:`bool`	if nonzero (default), call `BaseCache.on_leave` on the removed element

lock: threading.Lock = ¶

thread-safety lock

max_size: int = ¶

max number of elements to cache

def _increment_access_counter(self, key): ¶

Increment the number of times an element has been accessed.

Parameters
key:hashable	key to increment counter for

Returns
`int`	the number of accesses after incrementation

def _replace_tail_if_necessary(self, key, element, allow_replacement=True): ¶

If there is yet no value for the key cached but the access count is higher than tail, add this value to the cache.

Parameters
key:hashable	key which is used to identify the element
element:any	element to cache
allow_replacement:`bool`	if this value is false, do not replace tail

Returns
`bool`	True if the element is now cached, False otherwise

_key2le: dict = ¶

Undocumented

_list = ¶

Undocumented

_num_accesses: dict = ¶

Undocumented