( )⚙ 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
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

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 28036

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 deals with revisions' "index entries", 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!
objects that contains the same "items" whatever the revlog version.
Different versions will have different ways of storing these items (sometimes
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 code that relies
on the existing order. The field are defined as follows:
[0] offset:
The byte index of the start of revision data chunk.
That value is shifted up by 16 bits. use "offset = field >> 16" to
retrieve it.
flags:
A flag field that carries special information or changes the behavior
of the revision. (see `REVIDX_*` constants for details)
The flag field only occupies the first 16 bits of this field,
use "flags = field & 0xFFFF" to retrieve 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 delta (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's side-data chunk.
[9] sidedata chunk length:
The size, in bytes, of the revision's side-data chunk.
""" """
_flagserrorclass = error.RevlogError _flagserrorclass = error.RevlogError
def __init__( def __init__(
self, self,
opener, opener,
target, target,