git/pack-revindex.h
Taylor Blau dbd5c520d2 pack-revindex: implement midx_pair_to_pack_pos()
Now that we have extracted the `midx_key_to_pack_pos()` function, we can
implement the `midx_pair_to_pack_pos()` function which accepts (pack_id,
offset) tuples and returns an index into the psuedo-pack order.

This will be used in a following commit in order to figure out whether
or not the MIDX chose a given delta's base object from the same pack as
the delta resides in. It will do so by locating the base object's offset
in the pack, and then performing a binary search using the same pack ID
with the base object's offset.

If (and only if) it finds a match (at any position) we can guarantee
that the MIDX selected both halves of the delta/base pair from the same
pack.

Signed-off-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2023-12-14 14:38:08 -08:00

149 lines
4.9 KiB
C

#ifndef PACK_REVINDEX_H
#define PACK_REVINDEX_H
/**
* A revindex allows converting efficiently between three properties
* of an object within a pack:
*
* - index position: the numeric position within the list of sorted object ids
* found in the .idx file
*
* - pack position: the numeric position within the list of objects in their
* order within the actual .pack file (i.e., 0 is the first object in the
* .pack, 1 is the second, and so on)
*
* - offset: the byte offset within the .pack file at which the object contents
* can be found
*
* The revindex can also be used with a multi-pack index (MIDX). In this
* setting:
*
* - index position refers to an object's numeric position within the MIDX
*
* - pack position refers to an object's position within a non-existent pack
* described by the MIDX. The pack structure is described in
* gitformat-pack(5).
*
* It is effectively a concatanation of all packs in the MIDX (ordered by
* their numeric ID within the MIDX) in their original order within each
* pack), removing duplicates, and placing the preferred pack (if any)
* first.
*/
#define RIDX_SIGNATURE 0x52494458 /* "RIDX" */
#define RIDX_VERSION 1
#define GIT_TEST_NO_WRITE_REV_INDEX "GIT_TEST_NO_WRITE_REV_INDEX"
#define GIT_TEST_REV_INDEX_DIE_IN_MEMORY "GIT_TEST_REV_INDEX_DIE_IN_MEMORY"
#define GIT_TEST_REV_INDEX_DIE_ON_DISK "GIT_TEST_REV_INDEX_DIE_ON_DISK"
struct packed_git;
struct multi_pack_index;
struct repository;
/*
* load_pack_revindex populates the revindex's internal data-structures for the
* given pack, returning zero on success and a negative value otherwise.
*
* If a '.rev' file is present it is mmap'd, and pointers are assigned into it
* (instead of using the in-memory variant).
*/
int load_pack_revindex(struct repository *r, struct packed_git *p);
/*
* Specifically load a pack revindex from disk.
*
* Returns 0 on success, 1 on "no .rev file", and -1 when there is an
* error parsing the .rev file.
*/
int load_pack_revindex_from_disk(struct packed_git *p);
/*
* verify_pack_revindex verifies that the on-disk rev-index for the given
* pack-file is the same that would be created if written from scratch.
*
* A negative number is returned on error.
*/
int verify_pack_revindex(struct packed_git *p);
/*
* load_midx_revindex loads the '.rev' file corresponding to the given
* multi-pack index by mmap-ing it and assigning pointers in the
* multi_pack_index to point at it.
*
* A negative number is returned on error.
*/
int load_midx_revindex(struct multi_pack_index *m);
/*
* Frees resources associated with a multi-pack reverse index.
*
* A negative number is returned on error.
*/
int close_midx_revindex(struct multi_pack_index *m);
/*
* offset_to_pack_pos converts an object offset to a pack position. This
* function returns zero on success, and a negative number otherwise. The
* parameter 'pos' is usable only on success.
*
* If the reverse index has not yet been loaded, this function loads it lazily,
* and returns an negative number if an error was encountered.
*
* This function runs in time O(log N) with the number of objects in the pack.
*/
int offset_to_pack_pos(struct packed_git *p, off_t ofs, uint32_t *pos);
/*
* pack_pos_to_index converts the given pack-relative position 'pos' by
* returning an index-relative position.
*
* If the reverse index has not yet been loaded, or the position is out of
* bounds, this function aborts.
*
* This function runs in constant time.
*/
uint32_t pack_pos_to_index(struct packed_git *p, uint32_t pos);
/*
* pack_pos_to_offset converts the given pack-relative position 'pos' into a
* pack offset. For a pack with 'N' objects, asking for position 'N' will return
* the total size (in bytes) of the pack.
*
* If the reverse index has not yet been loaded, or the position is out of
* bounds, this function aborts.
*
* This function runs in constant time under both in-memory and on-disk reverse
* indexes, but an additional step is taken to consult the corresponding .idx
* file when using the on-disk format.
*/
off_t pack_pos_to_offset(struct packed_git *p, uint32_t pos);
/*
* pack_pos_to_midx converts the object at position "pos" within the MIDX
* pseudo-pack into a MIDX position.
*
* If the reverse index has not yet been loaded, or the position is out of
* bounds, this function aborts.
*
* This function runs in constant time.
*/
uint32_t pack_pos_to_midx(struct multi_pack_index *m, uint32_t pos);
/*
* midx_to_pack_pos converts from the MIDX-relative position at "at" to the
* corresponding pack position.
*
* If the reverse index has not yet been loaded, or the position is out of
* bounds, this function aborts.
*
* This function runs in time O(log N) with the number of objects in the MIDX.
*/
int midx_to_pack_pos(struct multi_pack_index *midx, uint32_t at, uint32_t *pos);
int midx_pair_to_pack_pos(struct multi_pack_index *midx, uint32_t pack_id,
off_t ofs, uint32_t *pos);
#endif