Patchwork D3943: scmutil: rewrite docstring for filecache

mail settings
Submitter phabricator
Date July 14, 2018, 1:42 a.m.
Message ID <8fab818c0f6ee68ad743804ff64fbdcc@localhost.localdomain>
Download mbox | patch
Permalink /patch/32837/
State Not Applicable
Headers show


phabricator - July 14, 2018, 1:42 a.m.
This revision was automatically updated to reflect the committed changes.
Closed by commit rHG3b072388ca78: scmutil: rewrite docstring for filecache (authored by indygreg, committed by ).

  rHG Mercurial





To: indygreg, #hg-reviewers
Cc: mercurial-devel


diff --git a/mercurial/ b/mercurial/
--- a/mercurial/
+++ b/mercurial/
@@ -1166,21 +1166,32 @@ 
 class filecache(object):
-    '''A property like decorator that tracks files under .hg/ for updates.
+    """A property like decorator that tracks files under .hg/ for updates.
-    Records stat info when called in _filecache.
+    On first access, the files defined as arguments are stat()ed and the
+    results cached. The decorated function is called. The results are stashed
+    away in a ``_filecache`` dict on the object whose method is decorated.
-    On subsequent calls, compares old stat info with new info, and recreates the
-    object when any of the files changes, updating the new stat info in
-    _filecache.
+    On subsequent access, the cached result is returned.
+    On external property set operations, stat() calls are performed and the new
+    value is cached.
+    On property delete operations, cached data is removed.
-    Mercurial either atomic renames or appends for files under .hg,
-    so to ensure the cache is reliable we need the filesystem to be able
-    to tell us if a file has been replaced. If it can't, we fallback to
-    recreating the object on every call (essentially the same behavior as
-    propertycache).
+    When using the property API, cached data is always returned, if available:
+    no stat() is performed to check if the file has changed and if the function
+    needs to be called to reflect file changes.
-    '''
+    Others can muck about with the state of the ``_filecache`` dict. e.g. they
+    can populate an entry before the property's getter is called. In this case,
+    entries in ``_filecache`` will be used during property operations,
+    if available. If the underlying file changes, it is up to external callers
+    to reflect this by e.g. calling ``delattr(obj, attr)`` to remove the cached
+    method result as well as possibly calling ``del obj._filecache[attr]`` to
+    remove the ``filecacheentry``.
+    """
     def __init__(self, *paths):
         self.paths = paths