Update README/introduction docs

[tkem]

cachetools now features much more than cache classes, so the introduction pycon samples should also show use of the decorators and maybe custom keys.

[tkem]

Maybe the docs should state more prominently that multi-threaded access to cache instances must be locked properly. Seems to be a recurring issue, e.g. #80, http://www.paulsprogrammingnotes.com/2016/08/python-cachetools-lrucache-keyerror.html.

[tkem]

E.g. "contrary to popular believe, cache instances are not thread safe - neither is, for example, OrderedDict".

[tkem]

BTW, is anywhere mentioned that the func decorators are thread-safe by default?

[jpivarski]

Is this still true? I want to use cachetools.LRUCache (not the function decorator; the dict-like class) and share that cache across threads. I can guarantee that I will only read from it using

lrucache.get(keystring, None)

and only write to it using

lrucache[keystring] = array

I don't mind if reads are stale (correct for some time in the past), but I do want to be sure that I don't corrupt the state with concurrent __setitem__ or read an invalid result if the read is concurrent with a write.

Can I make these assumptions or do I need to lock it just to be safe? (Locking with my current cache implementation is a performance bottleneck.)

[tkem]

You need to lock all access to the cache.

[jpivarski]

Okay, thanks for the info.