Mercurial > hg
diff mercurial/revlog.py @ 27070:7860366b46c9
revlog: improve documentation
There are a lot of functions and variables doing similar things.
Document the role and functionality of each to make it easier to
grok.
author | Gregory Szorc <gregory.szorc@gmail.com> |
---|---|
date | Sun, 22 Nov 2015 16:23:20 -0800 |
parents | dfab6edb98e3 |
children | 5ebc4a192550 |
line wrap: on
line diff
--- a/mercurial/revlog.py Sat Nov 21 22:28:01 2015 -0800 +++ b/mercurial/revlog.py Sun Nov 22 16:23:20 2015 -0800 @@ -205,14 +205,21 @@ self.indexfile = indexfile self.datafile = indexfile[:-2] + ".d" self.opener = opener + # 3-tuple of (node, rev, text) for a raw revision. self._cache = None + # 2-tuple of (rev, baserev) defining the base revision the delta chain + # begins at for a revision. self._basecache = None + # 2-tuple of (offset, data) of raw data from the revlog at an offset. self._chunkcache = (0, '') + # How much data to read and cache into the raw revlog data cache. self._chunkcachesize = 65536 self._maxchainlen = None self._aggressivemergedeltas = False self.index = [] + # Mapping of partial identifiers to full nodes. self._pcache = {} + # Mapping of revision integer to full node. self._nodecache = {nullid: nullrev} self._nodepos = None @@ -926,6 +933,10 @@ return hash(text, p1, p2) != node def _addchunk(self, offset, data): + """Add a segment to the revlog cache. + + Accepts an absolute offset and the data that is at that location. + """ o, d = self._chunkcache # try to add to existing cache if o + len(d) == offset and len(d) + len(data) < _chunksize: @@ -934,13 +945,15 @@ self._chunkcache = offset, data def _loadchunk(self, offset, length, df=None): - """Load a chunk/segment from the revlog. + """Load a segment of raw data from the revlog. - Accepts absolute offset, length to read, and an optional existing + Accepts an absolute offset, length to read, and an optional existing file handle to read from. If an existing file handle is passed, it will be seeked and the original seek position will NOT be restored. + + Returns a str or buffer of raw byte data. """ if df is not None: closehandle = False @@ -968,6 +981,16 @@ return d def _getchunk(self, offset, length, df=None): + """Obtain a segment of raw data from the revlog. + + Accepts an absolute offset, length of bytes to obtain, and an + optional file handle to the already-opened revlog. If the file + handle is used, it's original seek position will not be preserved. + + Requests for data may be returned from a cache. + + Returns a str or a buffer instance of raw byte data. + """ o, d = self._chunkcache l = len(d) @@ -982,6 +1005,18 @@ return self._loadchunk(offset, length, df=df) def _chunkraw(self, startrev, endrev, df=None): + """Obtain a segment of raw data corresponding to a range of revisions. + + Accepts the start and end revisions and an optional already-open + file handle to be used for reading. If the file handle is read, its + seek position will not be preserved. + + Requests for data may be satisfied by a cache. + + Returns a str or a buffer instance of raw byte data. Callers will + need to call ``self.start(rev)`` and ``self.length()`` to determine + where each revision's data begins and ends. + """ start = self.start(startrev) end = self.end(endrev) if self._inline: @@ -991,12 +1026,29 @@ return self._getchunk(start, length, df=df) def _chunk(self, rev, df=None): + """Obtain a single decompressed chunk for a revision. + + Accepts an integer revision and an optional already-open file handle + to be used for reading. If used, the seek position of the file will not + be preserved. + + Returns a str holding uncompressed data for the requested revision. + """ return decompress(self._chunkraw(rev, rev, df=df)) def _chunks(self, revs, df=None): - '''faster version of [self._chunk(rev) for rev in revs] + """Obtain decompressed chunks for the specified revisions. - Assumes that revs is in ascending order.''' + Accepts an iterable of numeric revisions that are assumed to be in + ascending order. Also accepts an optional already-open file handle + to be used for reading. If used, the seek position of the file will + not be preserved. + + This function is similar to calling ``self._chunk()`` multiple times, + but is faster. + + Returns a list with decompressed data for each requested revision. + """ if not revs: return [] start = self.start @@ -1032,6 +1084,7 @@ return l def _chunkclear(self): + """Clear the raw chunk cache.""" self._chunkcache = (0, '') def deltaparent(self, rev):