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  * 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.
  76  */
  77 int load_midx_revindex(struct multi_pack_index *m);
  78
  79 /*
  80  * Frees resources associated with a multi-pack reverse index.
  81  *
  82  * A negative number is returned on error.
  83  */
  84 int close_midx_revindex(struct multi_pack_index *m);
  85
  86 /*
  87  * offset_to_pack_pos converts an object offset to a pack position. This
  88  * function returns zero on success, and a negative number otherwise. The
  89  * parameter 'pos' is usable only on success.
  90  *
  91  * If the reverse index has not yet been loaded, this function loads it lazily,
  92  * and returns an negative number if an error was encountered.
  93  *
  94  * This function runs in time O(log N) with the number of objects in the pack.
  95  */
  96 int offset_to_pack_pos(struct packed_git *p, off_t ofs, uint32_t *pos);
  97
  98 /*
  99  * pack_pos_to_index converts the given pack-relative position 'pos' by
 100  * returning an index-relative position.
 101  *
 102  * If the reverse index has not yet been loaded, or the position is out of
 103  * bounds, this function aborts.
 104  *
 105  * This function runs in constant time.
 106  */
 107 uint32_t pack_pos_to_index(struct packed_git *p, uint32_t pos);
 108
 109 /*
 110  * pack_pos_to_offset converts the given pack-relative position 'pos' into a
 111  * pack offset. For a pack with 'N' objects, asking for position 'N' will return
 112  * the total size (in bytes) of the pack.
 113  *
 114  * If the reverse index has not yet been loaded, or the position is out of
 115  * bounds, this function aborts.
 116  *
 117  * This function runs in constant time under both in-memory and on-disk reverse
 118  * indexes, but an additional step is taken to consult the corresponding .idx
 119  * file when using the on-disk format.
 120  */
 121 off_t pack_pos_to_offset(struct packed_git *p, uint32_t pos);
 122
 123 /*
 124  * pack_pos_to_midx converts the object at position "pos" within the MIDX
 125  * pseudo-pack into a MIDX position.
 126  *
 127  * If the reverse index has not yet been loaded, or the position is out of
 128  * bounds, this function aborts.
 129  *
 130  * This function runs in constant time.
 131  */
 132 uint32_t pack_pos_to_midx(struct multi_pack_index *m, uint32_t pos);
 133
 134 /*
 135  * midx_to_pack_pos converts from the MIDX-relative position at "at" to the
 136  * corresponding pack position.
 137  *
 138  * If the reverse index has not yet been loaded, or the position is out of
 139  * bounds, this function aborts.
 140  *
 141  * This function runs in time O(log N) with the number of objects in the MIDX.
 142  */
 143 int midx_to_pack_pos(struct multi_pack_index *midx, uint32_t at, uint32_t *pos);
 144
 145 #endif