revlog: move entry documentation alongside new related constants
ClosedPublic

Authored by marmoute on May 30 2021, 1:29 PM.

Download Raw Diff

Details

Reviewers

indygreg
Alphare

Group Reviewers

hg-reviewers

Commits

rHG7a0ec25d5836: revlog: move entry documentation alongside new related constants

Summary

Accessing individual index-entry element is usually done using integer directly.
This is presumably for "performance reasons". However as the index entry gain
more and more element it seems useful to get the option to use symbolic constant
to access item, for both clarify and versatility. We will probably keep using
integer for performance critical path, but less critical code may start using
them now that they are declared.

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 30 2021, 1:29 PM

Herald added a reviewer: indygreg. · View Herald TranscriptMay 30 2021, 1:29 PM

Herald added a reviewer: hg-reviewers. · View Herald Transcript

Herald added a subscriber: mercurial-patches. · View Herald Transcript

marmoute added a child revision: D10792: revlog: move `offset_type` to `revlogutils`.May 30 2021, 1:29 PM

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

Alphare accepted this revision as: Alphare.May 31 2021, 10:36 AM

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

marmoute added a commit: rHG7a0ec25d5836: revlog: move entry documentation alongside new related constants.Jun 7 2021, 5:24 AM

This revision was not accepted when it landed; it landed in state Needs Review.

Closed by commit rHG7a0ec25d5836: revlog: move entry documentation alongside new related constants (authored by marmoute). · Explain Why

This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

			Path	Packages
M			mercurial/revlog.py (62 lines)
M			mercurial/revlogutils/constants.py (75 lines)

Diff	ID	Description	Created	Lint	Unit
Base		Base
Diff 1	28257		May 30 2021, 1:29 PM	★	★
Diff 2	28304		May 31 2021, 6:51 AM	★	★
Diff 3	28319		May 31 2021, 4:21 PM	★	★
Diff 4	28401		Jun 1 2021, 11:17 PM	★	★
Diff 5	28416		Jun 2 2021, 7:43 AM	★	★
Diff 6	28450		Jun 4 2021, 11:05 AM	★	★
Diff 7	28472		Jun 7 2021, 5:16 AM	★	★
Diff 8	28494	rHG7a0ec25d5836a99bad0a72986ef8d6a5f324eb6b	May 21 2021, 6:06 PM	★	★

Status	Author	Revision
Closed	marmoute	D10800 revlog: allow to pass an existing docket to `_loadindex()`
Closed	marmoute	D10799 revlog: add a ways to blacklist some revision when searching for a delta
Closed	marmoute	D10798 util: add `nb_bytes` argument to `copyfile` to partially copy a file
Closed	marmoute	D10797 revlog: move `revisioninfo` in `revlogutils`
Closed	marmoute	D10796 revlog: use the `entry` function in bundlerepo
Closed	marmoute	D10795 revlog: use entry in revlogv0.py
Closed	marmoute	D10794 revlog: use the new `entry` function in revlog.py
Closed	marmoute	D10793 revlog: add a function to build index entry tuple
Closed	marmoute	D10792 revlog: move `offset_type` to `revlogutils`
Closed	marmoute	D10791 revlog: move entry documentation alongside new related constants
Closed	marmoute	D10790 censor: drop size limitation on the tombstone
Closed	marmoute	D10789 revlog: move censoring code in a dedicated module
Closed	marmoute	D10788 censor: reduce risk of censor test blowing up output limit
Closed	marmoute	D10787 revlog: store sidedata in their own file
Closed	marmoute	D10786 revlog: fix docket.date_filepath docstring
Closed	marmoute	D10785 revlog: use dedicated code for reading sidedata
Closed	marmoute	D10784 revlog: simplify "partial read" error message
Closed	marmoute	D10783 revlog: no longer return sidedata from `_revisiondata`
Closed	marmoute	D10782 revlog: use `self.sidedata` directly in `revlog.clone`
Closed	marmoute	D10781 revlog: use `self.sidedata` directly to construct changelogrevision
Closed	marmoute	D10780 revlog: implement sidedata without using _revisiondata
Closed	marmoute	D10779 revlogv2: drop "sidedatacompression" from the list of todos
Closed	marmoute	D10831 index: use an explicit constant for INDEX_HEADER format and use it for docket

Diff 28494

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).

				See mercurial/revlogutils/contants.py for details about the content of an
	Internal details			index entry.
	----------------

	A large part of the revlog logic deals with revisions' "index entries", tuple
	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.

	[10] data compression mode:
	two bits that detail the way the data chunk is compressed on disk.
	(see "COMP_MODE_*" constants for details). For revlog version 0 and
	1 this will always be COMP_MODE_INLINE.

	[11] side-data compression mode:
	two bits that detail the way the sidedata chunk is compressed on disk.
	(see "COMP_MODE_*" constants for details)
	"""			"""

	_flagserrorclass = error.RevlogError			_flagserrorclass = error.RevlogError

	def __init__(			def __init__(
	self,			self,
	opener,			opener,
	target,			target,

mercurial/revlogutils/constants.py


	ALL_KINDS = {			ALL_KINDS = {
	KIND_CHANGELOG,			KIND_CHANGELOG,
	KIND_MANIFESTLOG,			KIND_MANIFESTLOG,
	KIND_FILELOG,			KIND_FILELOG,
	KIND_OTHER,			KIND_OTHER,
	}			}

				### Index entry key
				#
				#
				# Internal details
				# ----------------
				#
				# A large part of the revlog logic deals with revisions' "index entries", tuple
				# 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.
				ENTRY_DATA_OFFSET = 0

				# [1] compressed length:
				# The size, in bytes, of the chunk on disk
				ENTRY_DATA_COMPRESSED_LENGTH = 1

				# [2] uncompressed length:
				# The size, in bytes, of the full revision once reconstructed.
				ENTRY_DATA_UNCOMPRESSED_LENGTH = 2

				# [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.
				ENTRY_DELTA_BASE = 3

				# [4] link rev:
				# Changelog revision number of the changeset introducing this
				# revision.
				ENTRY_LINK_REV = 4

				# [5] parent 1 rev:
				# Revision number of the first parent
				ENTRY_PARENT_1 = 5

				# [6] parent 2 rev:
				# Revision number of the second parent
				ENTRY_PARENT_2 = 6

				# [7] node id:
				# The node id of the current revision
				ENTRY_NODE_ID = 7

				# [8] sidedata offset:
				# The byte index of the start of the revision's side-data chunk.
				ENTRY_SIDEDATA_OFFSET = 8

				# [9] sidedata chunk length:
				# The size, in bytes, of the revision's side-data chunk.
				ENTRY_SIDEDATA_COMPRESSED_LENGTH = 9

				# [10] data compression mode:
				# two bits that detail the way the data chunk is compressed on disk.
				# (see "COMP_MODE_*" constants for details). For revlog version 0 and
				# 1 this will always be COMP_MODE_INLINE.
				ENTRY_DATA_COMPRESSION_MODE = 10

				# [11] side-data compression mode:
				# two bits that detail the way the sidedata chunk is compressed on disk.
				# (see "COMP_MODE_*" constants for details)
				ENTRY_SIDEDATA_COMPRESSION_MODE = 11

	### main revlog header			### main revlog header

	# We cannot rely on Struct.format is inconsistent for python <=3.6 versus above			# We cannot rely on Struct.format is inconsistent for python <=3.6 versus above
	INDEX_HEADER_FMT = b">I"			INDEX_HEADER_FMT = b">I"
	INDEX_HEADER = struct.Struct(INDEX_HEADER_FMT)			INDEX_HEADER = struct.Struct(INDEX_HEADER_FMT)

	## revlog version			## revlog version
	REVLOGV0 = 0			REVLOGV0 = 0

This is an archive of the discontinued Mercurial Phabricator instance.

revlog: move entry documentation alongside new related constantsClosedPublic