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 #define RIDX_SIGNATURE 0x52494458 /* "RIDX" */
  20 #define RIDX_VERSION 1
  21
  22 struct packed_git;
  23
  24 /*
  25  * load_pack_revindex populates the revindex's internal data-structures for the
  26  * given pack, returning zero on success and a negative value otherwise.
  27  *
  28  * If a '.rev' file is present it is mmap'd, and pointers are assigned into it
  29  * (instead of using the in-memory variant).
  30  */
  31 int load_pack_revindex(struct packed_git *p);
  32
  33 /*
  34  * offset_to_pack_pos converts an object offset to a pack position. This
  35  * function returns zero on success, and a negative number otherwise. The
  36  * parameter 'pos' is usable only on success.
  37  *
  38  * If the reverse index has not yet been loaded, this function loads it lazily,
  39  * and returns an negative number if an error was encountered.
  40  *
  41  * This function runs in time O(log N) with the number of objects in the pack.
  42  */
  43 int offset_to_pack_pos(struct packed_git *p, off_t ofs, uint32_t *pos);
  44
  45 /*
  46  * pack_pos_to_index converts the given pack-relative position 'pos' by
  47  * returning an index-relative position.
  48  *
  49  * If the reverse index has not yet been loaded, or the position is out of
  50  * bounds, this function aborts.
  51  *
  52  * This function runs in constant time.
  53  */
  54 uint32_t pack_pos_to_index(struct packed_git *p, uint32_t pos);
  55
  56 /*
  57  * pack_pos_to_offset converts the given pack-relative position 'pos' into a
  58  * pack offset. For a pack with 'N' objects, asking for position 'N' will return
  59  * the total size (in bytes) of the pack.
  60  *
  61  * If the reverse index has not yet been loaded, or the position is out of
  62  * bounds, this function aborts.
  63  *
  64  * This function runs in constant time under both in-memory and on-disk reverse
  65  * indexes, but an additional step is taken to consult the corresponding .idx
  66  * file when using the on-disk format.
  67  */
  68 off_t pack_pos_to_offset(struct packed_git *p, uint32_t pos);
  69
  70 #endif