Package: darts.util.lru
LRU Dictionaries>>> from darts.lib.utils.lru import LRUDictAnLRUDictis basically a simple dictionary, which has a defined
maximum capacity, that may be supplied at construction time, or modified
at run-time via thecapacityproperty:>>> cache = LRUDict(1)
>>> cache.capacity
1The minimum capacity value is 1, and LRU dicts will complain, if someone
attempts to use a value smaller than that:>>> cache.capacity = -1                              #doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: -1 is not a valid capacity
>>> LRUDict(-1)                                      #doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: -1 is not a valid capacityLRU dictionaries can never contain more elements than their capacity value
indicates, so:>>> cache[1] = "First"
>>> cache[2] = "Second"
>>> len(cache)
1In order to ensure this behaviour, the dictionary will evict entries if
it needs to make room for new ones. So:>>> 1 in cache
False
>>> 2 in cache
TrueThe capacity can be adjusted at run-time. Growing the capacity does not
affect the number of elements present in an LRU dictionary:>>> cache.capacity = 3
>>> len(cache)
1
>>> cache[1] = "First"
>>> cache[3] = "Third"
>>> len(cache)
3but shrinking does:>>> cache.capacity = 2
>>> len(cache)
2
>>> sorted(list(cache.iterkeys()))
[1, 3]Note, that the entry with key2was evicted, because it was the oldest
entry at the time of the modification ofcapacity. The new oldest entry
is the one with key1, which can be seen, when we try to add another
entry to the dict:>>> cache[4] = "Fourth"
>>> sorted(list(cache.iterkeys()))
[3, 4]The following operations affect an entry’s priority:- `get`
- `__getitem__`
- `__setitem__`
- `__contains__`Calling any of these operations on an existing key will boost the key’s
priority, making it more unlikely to get evicted, when the dictionary needs
to make room for new entries. There is a specialpeekoperation, which
returns the current value associated to a key without boosting the priority
of the entry:>>> cache.peek(3)
'Third'
>>> cache[5] = "Fifth"
>>> sorted(list(cache.iterkeys()))
[4, 5]As you can see, even though we accessed the entry with key3as the last
one, the entry is now gone, because it did not get a priority boost from
the call topeek.The classLRUDictsupports a subset of the standard Pythondictinterface. In particular, we can iterate over the key, values, and
items of an LRU dict:>>> sorted([k for k in cache.iterkeys()])
[4, 5]
>>> sorted([v for v in cache.itervalues()])
['Fifth', 'Fourth']
>>> sorted([p for p in cache.iteritems()])
[(4, 'Fourth'), (5, 'Fifth')]
>>> sorted(list(cache))
[4, 5]Note, that there is no guaranteed order; in particular, the elements are
not generated in priority order or somesuch. Similar to regulardict`s,
an LRU dict’s `__iter__is actually any alias foriterkeys.Furthermore, we can remove all elements from the dict:>>> cache.clear()
>>> sorted(list(cache.iterkeys()))
[]Thread-safetyInstances of classLRUDictare not thread safe. Worse: even concurrent
read-only access is not thread-safe and has to be synchronized by the
client application.There is, however, the classSynchronizedLRUDict, which exposes the
same interface as plainLRUDict, but fully thread-safe. The following
session contains exactly the steps, we already tried with a plainLRUDict,
but now using the synchronized version:>>> from darts.lib.utils.lru import SynchronizedLRUDict
>>> cache = SynchronizedLRUDict(1)
>>> cache.capacity
1
>>> cache.capacity = -1                              #doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: -1 is not a valid capacity
>>> LRUDict(-1)                                      #doctest: +ELLIPSIS
Traceback (most recent call last):
...
ValueError: -1 is not a valid capacity
>>> cache[1] = "First"
>>> cache[2] = "Second"
>>> len(cache)
1
>>> 1 in cache
False
>>> 2 in cache
True
>>> cache.capacity = 3
>>> len(cache)
1
>>> cache[1] = "First"
>>> cache[3] = "Third"
>>> len(cache)
3
>>> cache.capacity = 2
>>> len(cache)
2
>>> sorted(list(cache.iterkeys()))
[1, 3]
>>> cache[4] = "Fourth"
>>> sorted(list(cache.iterkeys()))
[3, 4]
>>> cache.peek(3)
'Third'
>>> cache[5] = "Fifth"
>>> sorted(list(cache.iterkeys()))
[4, 5]
>>> sorted([k for k in cache.iterkeys()])
[4, 5]
>>> sorted([v for v in cache.itervalues()])
['Fifth', 'Fourth']
>>> sorted([p for p in cache.iteritems()])
[(4, 'Fourth'), (5, 'Fifth')]
>>> sorted(list(cache))
[4, 5]
>>> cache.clear()
>>> sorted(list(cache.iterkeys()))
[]Auto-loading CachesHaving some kind of dictionary which is capable of cleaning itself
up is nice, but in order to implement caching, there is still something
missing: the mechanism, which actually loads something into our dict.
This part of the story is implemented by theAutoLRUCache:>>> from darts.lib.utils.lru import AutoLRUCacheLet’s first define a load function:>>> def load_resource(key):
...    if key < 10:
...        print "Loading %r" % (key,)
...        return "R(%s)" % (key,)and a cache:>>> cache = AutoLRUCache(load_resource, capacity=3)
>>> cache.load(1)
Loading 1
'R(1)'
>>> cache.load(1)
'R(1)'As you can see, the first time, an actual element is loaded, the load
function provided to the constructor is called, in order to provide the
actual resource value. On subsequent calls toload, the cached value
is returned.Internally, theAutoLRUCacheclass uses anLRUDictto cache values,
so:>>> cache.load(2)
Loading 2
'R(2)'
>>> cache.load(3)
Loading 3
'R(3)'
>>> cache.load(4)
Loading 4
'R(4)'
>>> cache.load(1)
Loading 1
'R(1)'Note the “Loading 1” line in the last example. The cache has been initialized
with a capacity of 3, so the value of key1had to be evicted when the one
for key4was loaded. When we tried to obtain1again, the cache had to
properly reload it, calling the loader function.If there is actually no resource for a given key value, the loader function
must returnNone. It follows, thatNoneis never a valid resource value
to be associated with some key in anAutoLRUCache.>>> cache.load(11, 'Oops')
'Oops'Thread-safetyInstances of classAutoLRUCacheare fully thread safe. Be warned, though,
that the loader function is called outside of any synchronization scope the
class may internally use, and has to provide its own synchronization if
required.The cache class actually tries to minimize the number of invocations of the
loader by making sure, that no two concurrent threads will try to load the
same key value (though any number of concurrent threads might be busy loading
the resources associated with different keys).Caching and stale entriesThere is anotherAutoLRUCache-like class provided by the LRU module,
which gives more control over timing out of entries thanAutoLRUCachedoes.>>> from darts.lib.utils.lru import DecayingLRUCache
>>> current_time = 0
>>> def tick():
...     global current_time
...     current_time += 1Here, we defined a simple “clock”. We could have used the system clock,
but roling our own here gives us more control over the notion of “time”.
Now, let’s define a simple cache entry:>>> from collections import namedtuple
>>> Entry = namedtuple("Entry", "timestamp payload")
>>> def make_entry(payload):
...     return Entry(current_time, payload)and a loader function>>> def load(full_key):
...     print "Loading", full_key
...     return make_entry(u"Entry for %r" % (full_key,))For the following parts, we consider an entry to be “too old”, if it has
been created more then two “ticks” ago:>>> def is_still_current(entry):
...    return current_time - entry.timestamp <= 2Finally, we create another cache thingy>>> cache = DecayingLRUCache(load, tester=is_still_current, capacity=3)TheDecayingLRUCacheshows much of the same behaviour of theAutoLRUCache,
namely:>>> cache.load(1)
Loading 1
Entry(timestamp=0, payload=u'Entry for 1')
>>> cache.load(2)
Loading 2
Entry(timestamp=0, payload=u'Entry for 2')
>>> cache.load(3)
Loading 3
Entry(timestamp=0, payload=u'Entry for 3')
>>> cache.load(4)
Loading 4
Entry(timestamp=0, payload=u'Entry for 4')
>>> cache.load(1)
Loading 1
Entry(timestamp=0, payload=u'Entry for 1')The entry with key1had to be reloaded, since the cache has a capacity of
3, and the old entry for1was evicted when the entry for4was loaded
and we needed to make room.>>> cache.load(3)
Entry(timestamp=0, payload=u'Entry for 3')Now, let’s advance time>>> tick()
>>> cache.load(3)
Entry(timestamp=0, payload=u'Entry for 3')The entry is still available.>>> tick()
>>> cache.load(3)
Entry(timestamp=0, payload=u'Entry for 3')
>>> tick()
>>> cache.load(3)
Loading 3
Entry(timestamp=3, payload=u'Entry for 3')Note, that eviction is still based on LRU, not on the age test.Change LogVersion 0.5Added a “from __future__ import with_statement” for Python 2.5 compatibility.
Note, that supporting py2.5 is not a real goal, and I did not test the code
using that version.Version 0.4Added classDecayingLRUCacheVersion 0.3Added classSynchronizedLRUDictas thread-safe counterpart forLRUDict.