This is an archive of the discontinued Mercurial Phabricator instance.

Differential D3943

scmutil: rewrite docstring for filecache
ClosedPublic

Authored by indygreg on Jul 13 2018, 5:26 PM.

Details

Reviewers
None
Group Reviewers
hg-reviewers
Commits
rHG3b072388ca78: scmutil: rewrite docstring for filecache
Summary

The old docstring was incorrect in that it said that subsequent
calls perform a stat() and refresh the object if things change.
This is not how things work: get populates obj.dict[self.sname]
with the result of the decorated function and returns this value
without validation on subsequent calls, if available.

The correct usage of this type is kinda wonky. It would probably
benefit from a refactor. But I don't have time to do that right
now. But we can change the docstring so others aren't entrapped by
its lies (like I was when using repofilecache in a Mozilla extension).

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

indygreg created this revision.Jul 13 2018, 5:26 PM
Closed by commit rHG3b072388ca78: scmutil: rewrite docstring for filecache (authored by indygreg). · Explain WhyJul 13 2018, 9:42 PM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathPackages
Mmercurial/scmutil.py (33 lines)

Diff 9589

mercurial/scmutil.py

return True return True
return False return False
def refresh(self): def refresh(self):
for entry in self._entries: for entry in self._entries:
entry.refresh() entry.refresh()
class filecache(object): 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
On subsequent calls, compares old stat info with new info, and recreates the away in a ``_filecache`` dict on the object whose method is decorated.
object when any of the files changes, updating the new stat info in
_filecache. On subsequent access, the cached result is returned.
Mercurial either atomic renames or appends for files under .hg, On external property set operations, stat() calls are performed and the new
so to ensure the cache is reliable we need the filesystem to be able value is cached.
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 On property delete operations, cached data is removed.
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): def __init__(self, *paths):
self.paths = paths self.paths = paths
def join(self, obj, fname): def join(self, obj, fname):
"""Used to compute the runtime path of a cached file. """Used to compute the runtime path of a cached file.
Users should subclass filecache and provide their own version of this Users should subclass filecache and provide their own version of this
function to call the appropriate join function on 'obj' (an instance function to call the appropriate join function on 'obj' (an instance