( )⚙ D10643 revlog: improve documentation of the entry tuple

This is an archive of the discontinued Mercurial Phabricator instance.

Differential D10643

revlog: improve documentation of the entry tuple
ClosedPublic

Authored by marmoute on May 4 2021, 10:14 AM.

Details

Reviewers
indygreg
Alphare
Group Reviewers
hg-reviewers
Commits
rHG02a4463565ea: revlog: improve documentation of the entry tuple
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.

Diff Detail

Repository
rHG Mercurial
Branch
default
Lint
No Linters Available
Unit
No Unit Test Coverage

Event Timeline

marmoute created this revision.May 4 2021, 10:14 AM
baymax updated this revision to Diff 27882.May 11 2021, 1:45 PM

✅ refresh by Heptapod after a successful CI run (🐙 💚)

Alphare added a subscriber: Alphare.May 17 2021, 1:07 PM
Alphare added inline comments.
mercurial/revlog.py
292

I might take the liberty to fix the typos in flight. Thanks for the documentation!

Alphare accepted this revision.May 17 2021, 5:49 PM
This revision is now accepted and ready to land.May 17 2021, 5:49 PM
marmoute added a commit: rHG02a4463565ea: revlog: improve documentation of the entry tuple.May 17 2021, 5:54 PM
Closed by commit rHG02a4463565ea: revlog: improve documentation of the entry tuple (authored by marmoute). · Explain Why
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathPackages
Mmercurial/revlog.py (52 lines)

Diff 27882

mercurial/revlog.py

If `upperboundcomp` is not None, this is the expected maximal gain from If `upperboundcomp` is not None, this is the expected maximal gain from
compression for the data content. compression for the data content.
`concurrencychecker` is an optional function that receives 3 arguments: a `concurrencychecker` is an optional function that receives 3 arguments: a
file handle, a filename, and an expected position. It should check whether 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 the current position in the file handle is valid, and log/warn/fail (by
raising). raising).
Internal details
----------------
A large part of the revlog logic deal with revision "index entry" a tuple
AlphareUnsubmitted
Not Done

I might take the liberty to fix the typos in flight. Thanks for the documentation!

Alphare: I might take the liberty to fix the typos in flight. Thanks for the documentation!
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 _flagserrorclass = error.RevlogError
def __init__( def __init__(
self, self,
opener, opener,
target, target,