[PATCH] dirstate: add/improve method docstrings and some comments

Adrian Buehlmann adrian at cadifra.com
Fri Sep 25 18:09:33 CDT 2009


On 25.09.2009 23:08, Greg Ward wrote:
> # HG changeset patch
> # User Greg Ward <greg-hg at gerg.ca>
> # Date 1253912895 14400
> # Node ID a0a5ab02658efd960f23a7158f19eb14116ec737
> # Parent  1079b646b8591e57498690de542eecebb3979e38
> dirstate: add/improve method docstrings and some comments.
> 
> diff --git a/mercurial/dirstate.py b/mercurial/dirstate.py
...
> @@ -373,6 +380,13 @@
>              return
>          st = self._opener("dirstate", "w", atomictemp=True)
>  
> +        # Granularity is how we avoid problems with "write file, commit
> +        # file [and write dirstate], modify file" all happening within the
> +        # same second.  Specifically, if that happens, the dirstate entry
> +        # for file contains dummy entries for size and mtime, requiring the
> +        # caller of status() to read the file to see if it has actually
> +        # changed.  Setting granularity to zero is dangerous, since it
> +        # restores old, broken behaviour.
>          try:
>              gran = int(self._ui.config('dirstate', 'granularity', 1))
>          except ValueError:

No.

I try to explain (please forgive me if I fail, English is
not my primary language).

This happens most often on checkout, where mercurial writes
the file itself and updates the dirstate in the same second.

If such a file would be modified by a third party program
in that very same second again -- provided said modification
would *not* change the size of the file -- mercurial wouldn't
include that file as 'modified' in the next commit, because
it usually assumes that files which haven't changed in size
nor in mtime are *unchanged* without even looking into their
contents (mercurial's "blind second" problem).

With one exception. If mercurial finds a file's entry in the
dirstate marked as "unset" (a special marker for size and
mtime), it *will* look into the file contents as soon as status
information is wanted (either the user asks for that status info
or it is needed to determine whether a file must be included in
a check-in). At which point the file's entry in the dirstate is
'rectified' and the dirstate file updated.

So a 'hg status' call cleans up "unset" entries in
.hg/dirstate as a side effect -- provided the status call isn't
done too close in time to any mtime of any file having state
n ("normal").

(We are only talking about files having state 'n' in the dirstate
anyway here).

To avoid establishing the "blind-second" trap for a file,
mercurial checks the file's mtime when it updates the dirstate
(happens at the very end of transactions).

If the modification time of the dirstate (the reference point
is the modification time of the temporary file, newly created
for the updated dirstate file's contents) is the same as the
modification time of the file's entry in the dirstate, mercurial
"nullifies" the file's entry in the dirstate with the "unset"
marker to force it later to look inside the file unconditionally.

So this is a marker that says: "Always look into the file!".

Ugh. Does that help?

Anyway, it's pointless to try to describe the code with comments
in that level of detail.

The source code *is* the ultimate precise formal description of
the program. Too much comment is just a call for confusion and
disaster, as no one dares to update it or correct it if the code
is modified in the future.

The ultimate reader of the code is the python runtime.



More information about the Mercurial-devel mailing list