@leroysheep / Socializer
Code Commits Pulls CI/CD 81,841
master
bisect jch maint master next seen test todo
h 149 lines 5.01 KB
Raw
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 * The revindex can also be used with a multi-pack index (MIDX). In this
19 * setting:
20 *
21 * - index position refers to an object's numeric position within the MIDX
22 *
23 * - pack position refers to an object's position within a non-existent pack
24 * described by the MIDX. The pack structure is described in
25 * gitformat-pack(5).
26 *
27 * It is effectively a concatanation of all packs in the MIDX (ordered by
28 * their numeric ID within the MIDX) in their original order within each
29 * pack), removing duplicates, and placing the preferred pack (if any)
30 * first.
31 */
32
33
34 #define RIDX_SIGNATURE 0x52494458 /* "RIDX" */
35 #define RIDX_VERSION 1
36
37 #define GIT_TEST_NO_WRITE_REV_INDEX "GIT_TEST_NO_WRITE_REV_INDEX"
38 #define GIT_TEST_REV_INDEX_DIE_IN_MEMORY "GIT_TEST_REV_INDEX_DIE_IN_MEMORY"
39 #define GIT_TEST_REV_INDEX_DIE_ON_DISK "GIT_TEST_REV_INDEX_DIE_ON_DISK"
40
41 struct packed_git;
42 struct multi_pack_index;
43 struct repository;
44
45 /*
46 * load_pack_revindex populates the revindex's internal data-structures for the
47 * given pack, returning zero on success and a negative value otherwise.
48 *
49 * If a '.rev' file is present it is mmap'd, and pointers are assigned into it
50 * (instead of using the in-memory variant).
51 */
52 int load_pack_revindex(struct repository *r, struct packed_git *p);
53
54 /*
55 * Specifically load a pack revindex from disk.
56 *
57 * Returns 0 on success, 1 on "no .rev file", and -1 when there is an
58 * error parsing the .rev file.
59 */
60 int load_pack_revindex_from_disk(struct packed_git *p);
61
62 /*
63 * verify_pack_revindex verifies that the on-disk rev-index for the given
64 * pack-file is the same that would be created if written from scratch.
65 *
66 * A negative number is returned on error.
67 */
68 int verify_pack_revindex(struct packed_git *p);
69
70 /*
71 * load_midx_revindex loads the '.rev' file corresponding to the given
72 * multi-pack index by mmap-ing it and assigning pointers in the
73 * multi_pack_index to point at it.
74 *
75 * A negative number is returned on error. A positive number is returned in
76 * case the multi-pack-index does not have a reverse index.
77 */
78 int load_midx_revindex(struct multi_pack_index *m);
79
80 /*
81 * Frees resources associated with a multi-pack reverse index.
82 *
83 * A negative number is returned on error.
84 */
85 int close_midx_revindex(struct multi_pack_index *m);
86
87 /*
88 * offset_to_pack_pos converts an object offset to a pack position. This
89 * function returns zero on success, and a negative number otherwise. The
90 * parameter 'pos' is usable only on success.
91 *
92 * If the reverse index has not yet been loaded, this function loads it lazily,
93 * and returns an negative number if an error was encountered.
94 *
95 * This function runs in time O(log N) with the number of objects in the pack.
96 */
97 int offset_to_pack_pos(struct packed_git *p, off_t ofs, uint32_t *pos);
98
99 /*
100 * pack_pos_to_index converts the given pack-relative position 'pos' by
101 * returning an index-relative position.
102 *
103 * If the reverse index has not yet been loaded, or the position is out of
104 * bounds, this function aborts.
105 *
106 * This function runs in constant time.
107 */
108 uint32_t pack_pos_to_index(struct packed_git *p, uint32_t pos);
109
110 /*
111 * pack_pos_to_offset converts the given pack-relative position 'pos' into a
112 * pack offset. For a pack with 'N' objects, asking for position 'N' will return
113 * the total size (in bytes) of the pack.
114 *
115 * If the reverse index has not yet been loaded, or the position is out of
116 * bounds, this function aborts.
117 *
118 * This function runs in constant time under both in-memory and on-disk reverse
119 * indexes, but an additional step is taken to consult the corresponding .idx
120 * file when using the on-disk format.
121 */
122 off_t pack_pos_to_offset(struct packed_git *p, uint32_t pos);
123
124 /*
125 * pack_pos_to_midx converts the object at position "pos" within the MIDX
126 * pseudo-pack into a MIDX position.
127 *
128 * If the reverse index has not yet been loaded, or the position is out of
129 * bounds, this function aborts.
130 *
131 * This function runs in constant time.
132 */
133 uint32_t pack_pos_to_midx(struct multi_pack_index *m, uint32_t pos);
134
135 /*
136 * midx_to_pack_pos converts from the MIDX-relative position at "at" to the
137 * corresponding pack position.
138 *
139 * If the reverse index has not yet been loaded, or the position is out of
140 * bounds, this function aborts.
141 *
142 * This function runs in time O(log N) with the number of objects in the MIDX.
143 */
144 int midx_to_pack_pos(struct multi_pack_index *midx, uint32_t at, uint32_t *pos);
145
146 int midx_pair_to_pack_pos(struct multi_pack_index *midx, uint32_t pack_id,
147 off_t ofs, uint32_t *pos);
148
149 #endif