Memoize with Timeout

Function decorator and anciliary tooling to "memoize", or cache return values from a function call. Timeouts are important to ensure that the cache doesn't grow indefinitely, and has the advantage of culling on length since it is less subject to thrashing.

Getting Started

Installing

MWT can be installed using pip:

$ pip install mwt

If you want to run the latest version of the code, you can install from git:

$ pip install -U git+git://github.com/ak15199/mwt.git

Using MWT

At its simplest, simply decorate your method with MWT:

import timeit
from mwt import mwt

@mwt()
def fibonacci(n):
    a,b = 1,1

    for i in range(n-1):
        a,b = b,a+b

    return a

def test():
    fibonacci(5)

for i in range(5):
    print timeit.timeit("fibonacci(50000)", "from __main__ import fibonacci", number=1)

pi@pi:/tmp $ python fib.py
0.470113992691
4.10079956055e-05
3.50475311279e-05
3.88622283936e-05
2.59876251221e-05

A Note of Caution

Just because you can do something, it doesn't mean that you should.

The MWT decorator is a quick and easy way to resduce extended time in calculation, but it is by definition not perfect: there are overheads to the memoization and garbage collection process implicit in memoization, and caution in its use is presented.

In particular, watch out for the overall time executed, and secondly the cache hit ratio: if the percentage of hits is small, then the net effect is to add overhead, not reduce it.

There are two things that can be done to evaluate performance. The first and most obvious is to profile timings and see whether time overall has been saved with the addition of the decorator.

The other is to analyze cache statistics after the containing code has been running for a while. MWT provides a stats interface to assist with this, and it can be utilized like this:

fmt = "%-15s %8s %8s %8s %8s %8s %8s"
print(fmt%("Cache", "Length", "Hits", "Misses", "Purged",
        "Timeouts", "HWM"))
stats = mwt.stats()
for stat in stats:
    print(fmt%(stat["cache"], stat["length"], stat["hits"],
            stat["misses"], stat["purged"], stat["timeouts"],
            stat["hwm"]))

Which will produce output like this which will allow you to see how effective the memoization process is for each of the functions that are decorated:

Cache               Length    Hits   Misses   Purged Timeouts      HWM
opc.hue:rgbToHsv         0       0        0        0        0        0
opc.hue:hue              0       0        0        0        0        0
opc.hue:hsvToRgb     27167   32785      270     5103        0    27183

A high hit:miss ratio indicates that the cache is performing well.

If the ratio is poor, though, then don't give up straight away: it's possible that matters may be improved by tweaking the target method's calling parameters (for example, bounding a float to perhaps a couple of digits of precision).

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Alex King - Initial work - ak15199

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

Based on inspiration from MEMOIZE DECORATOR WITH TIMEOUT (PYTHON RECIPE)