Patchwork D10643: revlog: improve documentation of the entry tuple

login
register
mail settings
Submitter phabricator
Date May 4, 2021, 2:19 p.m.
Message ID <differential-rev-PHID-DREV-hb34cihaeyy6allndpwp-req@mercurial-scm.org>
Download mbox | patch
Permalink /patch/48964/
State Superseded
Headers show

Comments

phabricator - May 4, 2021, 2:19 p.m.
marmoute created this revision.
Herald added a reviewer: indygreg.
Herald added a reviewer: hg-reviewers.
Herald added a subscriber: mercurial-patches.

REVISION SUMMARY
  The code in revlog, and outside revlog directly use the index's entry tuple,
  with direct integer indexing. This is a voluntary trade off to obtains better
  performance from the  Python code at the expense of the developers sanity.
  
  Let's at least have a clear and central documentation about what this tuple is
  about.

REPOSITORY
  rHG Mercurial

BRANCH
  default

REVISION DETAIL
  https://phab.mercurial-scm.org/D10643

AFFECTED FILES
  mercurial/revlog.py

CHANGE DETAILS




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

Patch

diff --git a/mercurial/revlog.py b/mercurial/revlog.py
--- a/mercurial/revlog.py
+++ b/mercurial/revlog.py
@@ -284,6 +284,58 @@ 
     file handle, a filename, and an expected position. It should check whether
     the current position in the file handle is valid, and log/warn/fail (by
     raising).
+
+
+    Internal details
+    ----------------
+
+    A large part of the revlog logic deal with revision "index entry" a tuple
+    object that constains the same "items" whatever the revlog version.
+    Different version will have different way to store these items (sometime
+    not having them at all), but the tuple will always be the same. New fields
+    are usually added at the end to avoid breaking existing, other, code
+    relying on the existing order. The field are defined as follow:
+
+    [0] offset:
+            The byte index of the start of revision data chunk.
+            That value is shifted up by 16 bits. use "offsett = field >> 16" to
+            retrieve it.
+
+        flags:
+            A flag fields that carry special information or change the behavior
+            of the revision.  (see `REVIDX_*` constants for details)
+            The flag field only occupy the first 16 bits of this field,
+            use "flags = field && 0xFFFF" to retrive the value.
+
+    [1] compressed length:
+            The size, in bytes, of the chunk on disk
+
+    [2] uncompressed length:
+            The size, in bytes, of the full revision once reconstructed.
+
+    [3] base rev:
+            Either the base of the revision delta chain (without general
+            delta). Or the base of the delte (stored in the data chunk)
+            with general delta.
+
+    [4] link rev:
+            Changelog revision number of the changeset introducing this
+            revision.
+
+    [5] parent 1 rev:
+            Revision number of the first parent
+
+    [6] parent 2 rev:
+            Revision number of the second parent
+
+    [7] node id:
+            The node id of the current revision
+
+    [8] sidedata offset:
+            The byte index of the start of the revision side-data chunk.
+
+    [9] sidedata chunk length:
+            The size, in bytes, of the revision side-data chunk.
     """
 
     _flagserrorclass = error.RevlogError