Merge https://github.com/prati0100/git-gui
[git] / pack-revindex.h
1 #ifndef PACK_REVINDEX_H
2 #define PACK_REVINDEX_H
3
4 /**
5  * A revindex allows converting efficiently between three properties
6  * of an object within a pack:
7  *
8  * - index position: the numeric position within the list of sorted object ids
9  *   found in the .idx file
10  *
11  * - pack position: the numeric position within the list of objects in their
12  *   order within the actual .pack file (i.e., 0 is the first object in the
13  *   .pack, 1 is the second, and so on)
14  *
15  * - offset: the byte offset within the .pack file at which the object contents
16  *   can be found
17  */
18
19
20 #define RIDX_SIGNATURE 0x52494458 /* "RIDX" */
21 #define RIDX_VERSION 1
22
23 #define GIT_TEST_WRITE_REV_INDEX "GIT_TEST_WRITE_REV_INDEX"
24 #define GIT_TEST_REV_INDEX_DIE_IN_MEMORY "GIT_TEST_REV_INDEX_DIE_IN_MEMORY"
25
26 struct packed_git;
27
28 /*
29  * load_pack_revindex populates the revindex's internal data-structures for the
30  * given pack, returning zero on success and a negative value otherwise.
31  *
32  * If a '.rev' file is present it is mmap'd, and pointers are assigned into it
33  * (instead of using the in-memory variant).
34  */
35 int load_pack_revindex(struct packed_git *p);
36
37 /*
38  * offset_to_pack_pos converts an object offset to a pack position. This
39  * function returns zero on success, and a negative number otherwise. The
40  * parameter 'pos' is usable only on success.
41  *
42  * If the reverse index has not yet been loaded, this function loads it lazily,
43  * and returns an negative number if an error was encountered.
44  *
45  * This function runs in time O(log N) with the number of objects in the pack.
46  */
47 int offset_to_pack_pos(struct packed_git *p, off_t ofs, uint32_t *pos);
48
49 /*
50  * pack_pos_to_index converts the given pack-relative position 'pos' by
51  * returning an index-relative position.
52  *
53  * If the reverse index has not yet been loaded, or the position is out of
54  * bounds, this function aborts.
55  *
56  * This function runs in constant time.
57  */
58 uint32_t pack_pos_to_index(struct packed_git *p, uint32_t pos);
59
60 /*
61  * pack_pos_to_offset converts the given pack-relative position 'pos' into a
62  * pack offset. For a pack with 'N' objects, asking for position 'N' will return
63  * the total size (in bytes) of the pack.
64  *
65  * If the reverse index has not yet been loaded, or the position is out of
66  * bounds, this function aborts.
67  *
68  * This function runs in constant time under both in-memory and on-disk reverse
69  * indexes, but an additional step is taken to consult the corresponding .idx
70  * file when using the on-disk format.
71  */
72 off_t pack_pos_to_offset(struct packed_git *p, uint32_t pos);
73
74 #endif