[Python-checkins] cpython (3.3): Improve comments and variable names.

Sat Mar 9 05:15:17 CET 2013

http://hg.python.org/cpython/rev/1af9f7df3a96
changeset: 82558:1af9f7df3a96
branch: 3.3
parent: 82555:8817a09e012c
user: Raymond Hettinger <python at rcn.com>
date: Fri Mar 08 21:11:55 2013 -0700
summary:
 Improve comments and variable names.
files:
 Lib/functools.py | 51 ++++++++++++++++++++++++++---------
 1 files changed, 37 insertions(+), 14 deletions(-)

diff --git a/Lib/functools.py b/Lib/functools.py
--- a/Lib/functools.py
+++ b/Lib/functools.py
@@ -17,7 +17,7 @@
 from _thread import RLock
 except:
 class RLock:
- 'Dummy reentrant lock'
+ 'Dummy reentrant lock for builds without threads'
 def __enter__(self): pass
 def __exit__(self, exctype, excinst, exctb): pass
 
@@ -146,6 +146,12 @@
 _CacheInfo = namedtuple("CacheInfo", ["hits", "misses", "maxsize", "currsize"])
 
 class _HashedSeq(list):
+ """ This class guarantees that hash() will be called no more than once
+ per element. This is important because the lru_cache() will hash
+ the key multiple times on a cache miss.
+
+ """
+
 __slots__ = 'hashvalue'
 
 def __init__(self, tup, hash=hash):
@@ -159,7 +165,16 @@
 kwd_mark = (object(),),
 fasttypes = {int, str, frozenset, type(None)},
 sorted=sorted, tuple=tuple, type=type, len=len):
- 'Make a cache key from optionally typed positional and keyword arguments'
+ """Make a cache key from optionally typed positional and keyword arguments
+
+ The key is constructed in a way that is flat as possible rather than
+ as a nested structure that would take more memory.
+
+ If there is only a single argument and its data type is known to cache
+ its hash value, then that argument is returned without a wrapper. This
+ saves space and improves lookup speed.
+
+ """
 key = args
 if kwds:
 sorted_items = sorted(kwds.items())
@@ -217,7 +232,7 @@
 if maxsize == 0:
 
 def wrapper(*args, **kwds):
- # no caching, just a statistics update after a successful call
+ # No caching -- just a statistics update after a successful call
 nonlocal misses
 result = user_function(*args, **kwds)
 misses += 1
@@ -226,7 +241,7 @@
 elif maxsize is None:
 
 def wrapper(*args, **kwds):
- # simple caching without ordering or size limit
+ # Simple caching without ordering or size limit
 nonlocal hits, misses, currsize
 key = make_key(args, kwds, typed)
 result = cache_get(key, sentinel)
@@ -242,14 +257,14 @@
 else:
 
 def wrapper(*args, **kwds):
- # size limited caching that tracks accesses by recency
+ # Size limited caching that tracks accesses by recency
 nonlocal root, hits, misses, currsize, full
 key = make_key(args, kwds, typed)
 with lock:
 link = cache_get(key)
 if link is not None:
- # move the link to the front of the circular queue
- link_prev, link_next, key, result = link
+ # Move the link to the front of the circular queue
+ link_prev, link_next, _key, result = link
 link_prev[NEXT] = link_next
 link_next[PREV] = link_prev
 last = root[PREV]
@@ -261,26 +276,34 @@
 result = user_function(*args, **kwds)
 with lock:
 if key in cache:
- # getting here means that this same key was added to the
- # cache while the lock was released. since the link
+ # Getting here means that this same key was added to the
+ # cache while the lock was released. Since the link
 # update is already done, we need only return the
 # computed result and update the count of misses.
 pass
 elif full:
- # use the old root to store the new key and result
+ # Use the old root to store the new key and result.
 oldroot = root
 oldroot[KEY] = key
 oldroot[RESULT] = result
- # empty the oldest link and make it the new root
+ # Empty the oldest link and make it the new root.
+ # Keep a reference to the old key and old result to
+ # prevent their ref counts from going to zero during the
+ # update. That will prevent potentially arbitrary object
+ # clean-up code (i.e. __del__) from running while we're
+ # still adjusting the links.
 root = oldroot[NEXT]
 oldkey = root[KEY]
- oldvalue = root[RESULT]
+ oldresult = root[RESULT]
 root[KEY] = root[RESULT] = None
- # now update the cache dictionary for the new links
+ # Now update the cache dictionary.
 del cache[oldkey]
+ # Save the potentially reentrant cache[key] assignment
+ # for last, after the root and links have been put in
+ # a consistent state.
 cache[key] = oldroot
 else:
- # put result in a new link at the front of the queue
+ # Put result in a new link at the front of the queue.
 last = root[PREV]
 link = [last, root, key, result]
 last[NEXT] = root[PREV] = cache[key] = link
-- 
Repository URL: http://hg.python.org/cpython
