|
6 | 6 |
|
7 | 7 | .. _topics-index: |
8 | 8 |
|
9 | | -`caching.cache`: A caching decorator that understands arguments |
10 | | -=============================================================== |
| 9 | +`caching.cache` |
| 10 | +=============== |
| 11 | + |
| 12 | +A caching decorator that understands arguments |
| 13 | +---------------------------------------------- |
11 | 14 |
|
12 | 15 | The idea of a caching decorator is very cool. You decorate your function with a |
13 | 16 | caching decorator: |
@@ -60,17 +63,31 @@ Enter `caching.cache`: |
60 | 63 | Calculating |
61 | 64 | ('something_else', 2, {}) |
62 | 65 |
|
63 | | -That's the main cool thing about `caching.cache` |
| 66 | +As you can see above, `caching.cache` analyzes the function and understands |
| 67 | +that calls like ``g(1)`` and ``g(1, 2)`` are identical and therefore should be |
| 68 | +cached together. |
| 69 | + |
| 70 | + |
| 71 | +Both limited and unlimited cache |
| 72 | +-------------------------------- |
| 73 | + |
| 74 | +By default, the cache size will be unlimited. If you want to limit the cache size, pass in the `max_size` argument: |
| 75 | + |
| 76 | + >>> @caching.cache(max_size=7) |
| 77 | + ... def f(): pass |
| 78 | + |
| 79 | + |
| 80 | +If and when the cache size reaches the limit (7 in this case), old values will |
| 81 | +get thrown away according to a `LRU order`_. |
| 82 | + |
| 83 | + |
| 84 | +Sleekrefs |
| 85 | +---------- |
| 86 | + |
| 87 | +`caching.cache` arguments with sleekrefs. Sleekrefs are a more robust variation of `weakrefs`_. They are basically a gracefully-degrading version of weakrefs, so you can use them on un-weakreff-able objects like ``int``\s, and they will just use regular references. |
| 88 | + |
| 89 | +The usage of sleekrefs prevents memory leaks when using potentially-heavy arguments. |
64 | 90 |
|
65 | 91 |
|
66 | | -; It has other interesting features that I will not go in depth into: |
67 | | -<ul><li>It has a `max_size` argument which limits the size of the cache dict; old values get thrown away according to an <a href="http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used">LRU algorithm</a> implemented using (my bundled version of) Python’s <a href="http://docs.python.org/dev/library/collections.html#collections.OrderedDict">`OrderedDict`</a>, specifically the new <a href="http://docs.python.org/dev/library/collections.html#collections.OrderedDict.move_to_end">`OrderedDict.move_to_end`</a> method.</li> |
68 | | -<li>It stores arguments with <a href="https://github.com/cool-RR/GarlicSim/tree/master/garlicsim/garlicsim/general_misc/sleek_refs">sleekrefs</a>. Sleekrefs are a more robust variation of <a href="http://docs.python.org/library/weakref.html">weakrefs</a>. This prevents memory leaks when using potentially-heavy arguments. More about sleekrefs in a future blog post.</li> |
69 | | -<li> |
70 | | -It preserves the original function’s signature using <a href="http://www.artima.com/weblogs/index.jsp?blogger=micheles">Michele Simionato</a>’s excellent <a href="http://pypi.python.org/pypi/decorator">decorator module</a>. |
71 | | -</li> |
72 | | -</ul><h2>Source and tests for `caching.cache`</h2> |
73 | | -<a href="https://github.com/cool-RR/GarlicSim/blob/master/garlicsim/garlicsim/general_misc/caching/cache.py">Source for `caching.cache`, well-documented</a>. Here are <a href="https://github.com/cool-RR/GarlicSim/blob/master/garlicsim/test_garlicsim/test_general_misc/test_caching/test_cache.py">the tests</a>. |
74 | | -There is also a <a href="https://github.com/cool-RR/GarlicSim-for-Python-3.x/blob/master/garlicsim_py3/garlicsim/general_misc/caching/cache.py">Python 3 version of `caching.cache`</a>, and <a href="https://github.com/cool-RR/GarlicSim-for-Python-3.x/blob/master/garlicsim_py3/test_garlicsim/test_general_misc/test_caching/test_cache.py">here are its tests</a>. It’s available with the <a href="http://pypi.python.org/pypi/garlicsim_py3">Python 3 fork of GarlicSim</a>. Note that I haven’t tested it on Python 3’s <a href="http://www.python.org/dev/peps/pep-3102/">new kinds of function signatures</a>; I’ll be happy to get patches with tests and/or implementation of support for those. |
75 | | -<h2>Please give feedback!</h2> |
76 | | -I’ll be happy to get any opinions, critiques and code reviews on `caching.cache`! |
| 92 | +.. _LRU order: http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used |
| 93 | +.. _weakrefs: http://docs.python.org/library/weakref.html |
0 commit comments