git/oid-array.h

138 lines
4.3 KiB
C
Raw Normal View History

#ifndef OID_ARRAY_H
#define OID_ARRAY_H
oid-array: provide a for-loop iterator We provide oid_array_for_each_unique() for iterating over the de-duplicated items in an array. But it's awkward to use for two reasons: 1. It uses a callback, which means marshaling arguments into a struct and passing it to the callback with a void parameter. 2. The callback doesn't know the numeric index of the oid we're looking at. This is useful for things like progress meters. Iterating with a for-loop is much more natural for some cases, but the caller has to do the de-duping itself. However, we can provide a small helper to make this easier (see the docstring in the header for an example use). The caller does have to remember to sort the array first. We could add an assertion into the helper that array->sorted is set, but I didn't want to complicate what is otherwise a pretty fast code path. I also considered adding a full iterator type with init/next/end functions (similar to what we have for hashmaps). But it ended up making the callers much harder to read. This version keeps us close to a basic for-loop. Yet another option would be adding an option to sort the array and compact out the duplicates. This would mean iterating over the array an extra time, though that's probably not a big deal (we did just do an O(n log n) sort). But we'd still have to write a for-loop to iterate, so it doesn't really make anything easier for the caller. No new test, since we'll convert the callback iterator (which is covered by t0064, among other callers) to use the new code. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-07 19:11:00 +00:00
#include "hash.h"
/**
* The API provides storage and manipulation of sets of object identifiers.
* The emphasis is on storage and processing efficiency, making them suitable
* for large lists. Note that the ordering of items is not preserved over some
* operations.
*
* Examples
* --------
* -----------------------------------------
* int print_callback(const struct object_id *oid,
* void *data)
* {
* printf("%s\n", oid_to_hex(oid));
* return 0; // always continue
* }
*
* void some_func(void)
* {
* struct oid_array hashes = OID_ARRAY_INIT;
* struct object_id oid;
*
* // Read objects into our set
* while (read_object_from_stdin(oid.hash))
* oid_array_append(&hashes, &oid);
*
* // Check if some objects are in our set
* while (read_object_from_stdin(oid.hash)) {
* if (oid_array_lookup(&hashes, &oid) >= 0)
* printf("it's in there!\n");
*
* // Print the unique set of objects. We could also have
* // avoided adding duplicate objects in the first place,
* // but we would end up re-sorting the array repeatedly.
* // Instead, this will sort once and then skip duplicates
* // in linear time.
*
* oid_array_for_each_unique(&hashes, print_callback, NULL);
* }
*/
/**
* A single array of object IDs. This should be initialized by assignment from
* `OID_ARRAY_INIT`. The `oid` member contains the actual data. The `nr` member
* contains the number of items in the set. The `alloc` and `sorted` members
* are used internally, and should not be needed by API callers.
*/
struct oid_array {
struct object_id *oid;
oid_array: use size_t for count and allocation The oid_array object uses an "int" to store the number of items and the allocated size. It's rather unlikely for somebody to have more than 2^31 objects in a repository (the sha1's alone would be 40GB!), but if they do, we'd overflow our alloc variable. You can reproduce this case with something like: git init repo cd repo # make a pack with 2^24 objects perl -e ' my $nr = 2**24; for (my $i = 0; $i < $nr; $i++) { print "blob\n"; print "data 4\n"; print pack("N", $i); } ' | git fast-import # now make 256 copies of it; most of these objects will be duplicates, # but oid_array doesn't de-dup until all values are read and it can # sort the result. cd .git/objects/pack/ pack=$(echo *.pack) idx=$(echo *.idx) for i in $(seq 0 255); do # no need to waste disk space ln "$pack" "pack-extra-$i.pack" ln "$idx" "pack-extra-$i.idx" done # and now force an oid_array to store all of it git cat-file --batch-all-objects --batch-check which results in: fatal: size_t overflow: 32 * 18446744071562067968 So the good news is that st_mult() sees the problem (the large number is because our int wraps negative, and then that gets cast to a size_t), doing the job it was meant to: bailing in crazy situations rather than causing an undersized buffer. But we should avoid hitting this case at all, and instead limit ourselves based on what malloc() is willing to give us. We can easily do that by switching to size_t. The cat-file process above made it to ~120GB virtual set size before the integer overflow (our internal hash storage is 32-bytes now in preparation for sha256, so we'd expect ~128GB total needed, plus potentially more to copy from one realloc'd block to another)). After this patch (and about 130GB of RAM+swap), it does eventually read in the whole set. No test for obvious reasons. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-03-30 14:03:09 +00:00
size_t nr;
size_t alloc;
int sorted;
};
#define OID_ARRAY_INIT { NULL, 0, 0, 0 }
/**
* Add an item to the set. The object ID will be placed at the end of the array
* (but note that some operations below may lose this ordering).
*/
void oid_array_append(struct oid_array *array, const struct object_id *oid);
/**
* Perform a binary search of the array for a specific object ID. If found,
* returns the offset (in number of elements) of the object ID. If not found,
* returns a negative integer. If the array is not sorted, this function has
* the side effect of sorting it.
*/
int oid_array_lookup(struct oid_array *array, const struct object_id *oid);
/**
* Free all memory associated with the array and return it to the initial,
* empty state.
*/
void oid_array_clear(struct oid_array *array);
typedef int (*for_each_oid_fn)(const struct object_id *oid,
void *data);
/**
* Iterate over each element of the list, executing the callback function for
* each one. Does not sort the list, so any custom hash order is retained.
* If the callback returns a non-zero value, the iteration ends immediately
* and the callback's return is propagated; otherwise, 0 is returned.
*/
get_short_oid: sort ambiguous objects by type, then SHA-1 Change the output emitted when an ambiguous object is encountered so that we show tags first, then commits, followed by trees, and finally blobs. Within each type we show objects in hashcmp() order. Before this change the objects were only ordered by hashcmp(). The reason for doing this is that the output looks better as a result, e.g. the v2.17.0 tag before this change on "git show e8f2" would display: hint: The candidates are: hint: e8f2093055 tree hint: e8f21caf94 commit 2013-06-24 - bash prompt: print unique detached HEAD abbreviated object name hint: e8f21d02f7 blob hint: e8f21d577c blob hint: e8f25a3a50 tree hint: e8f26250fa commit 2017-02-03 - Merge pull request #996 from jeffhostetler/jeffhostetler/register_rename_src hint: e8f2650052 tag v2.17.0 hint: e8f2867228 blob hint: e8f28d537c tree hint: e8f2a35526 blob hint: e8f2bc0c06 commit 2015-05-10 - Documentation: note behavior for multiple remote.url entries hint: e8f2cf6ec0 tree Now we'll instead show: hint: e8f2650052 tag v2.17.0 hint: e8f21caf94 commit 2013-06-24 - bash prompt: print unique detached HEAD abbreviated object name hint: e8f26250fa commit 2017-02-03 - Merge pull request #996 from jeffhostetler/jeffhostetler/register_rename_src hint: e8f2bc0c06 commit 2015-05-10 - Documentation: note behavior for multiple remote.url entries hint: e8f2093055 tree hint: e8f25a3a50 tree hint: e8f28d537c tree hint: e8f2cf6ec0 tree hint: e8f21d02f7 blob hint: e8f21d577c blob hint: e8f2867228 blob hint: e8f2a35526 blob Since we show the commit data in the output that's nicely aligned once we sort by object type. The decision to show tags before commits is pretty arbitrary. I don't want to order by object_type since there tags come last after blobs, which doesn't make sense if we want to show the most important things first. I could display them after commits, but it's much less likely that we'll display a tag, so if there is one it makes sense to show it prominently at the top. A note on the implementation: Derrick rightly pointed out[1] that we're bending over backwards here in get_short_oid() to first de-duplicate the list, and then emit it, but could simply do it in one step. The reason for that is that oid_array_for_each_unique() doesn't actually require that the array be sorted by oid_array_sort(), it just needs to be sorted in some order that guarantees that all objects with the same ID are adjacent to one another, which (barring a hash collision, which'll be someone else's problem) the sort_ambiguous() function does. I agree that would be simpler for this code, and had forgotten why I initially wrote it like this[2]. But on further reflection I think it's better to do more work here just so we're not underhandedly using the oid-array API where we lie about the list being sorted. That would break any subsequent use of oid_array_lookup() in subtle ways. I could get around that by hacking the API itself to support this use-case and documenting it, which I did as a WIP patch in [3], but I think it's too much code smell just for this one call site. It's simpler for the API to just introduce a oid_array_for_each() function to eagerly spew out the list without sorting or de-duplication, and then do the de-duplication and sorting in two passes. 1. https://public-inbox.org/git/20180501130318.58251-1-dstolee@microsoft.com/ 2. https://public-inbox.org/git/876047ze9v.fsf@evledraar.gmail.com/ 3. https://public-inbox.org/git/874ljrzctc.fsf@evledraar.gmail.com/ Helped-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-10 12:43:02 +00:00
int oid_array_for_each(struct oid_array *array,
for_each_oid_fn fn,
void *data);
/**
* Iterate over each unique element of the list in sorted order, but otherwise
* behave like `oid_array_for_each`. If the array is not sorted, this function
* has the side effect of sorting it.
*/
int oid_array_for_each_unique(struct oid_array *array,
for_each_oid_fn fn,
void *data);
/**
* Apply the callback function `want` to each entry in the array, retaining
* only the entries for which the function returns true. Preserve the order
* of the entries that are retained.
*/
void oid_array_filter(struct oid_array *array,
for_each_oid_fn want,
void *cbdata);
/**
* Sort the array in order of ascending object id.
*/
void oid_array_sort(struct oid_array *array);
oid-array: provide a for-loop iterator We provide oid_array_for_each_unique() for iterating over the de-duplicated items in an array. But it's awkward to use for two reasons: 1. It uses a callback, which means marshaling arguments into a struct and passing it to the callback with a void parameter. 2. The callback doesn't know the numeric index of the oid we're looking at. This is useful for things like progress meters. Iterating with a for-loop is much more natural for some cases, but the caller has to do the de-duping itself. However, we can provide a small helper to make this easier (see the docstring in the header for an example use). The caller does have to remember to sort the array first. We could add an assertion into the helper that array->sorted is set, but I didn't want to complicate what is otherwise a pretty fast code path. I also considered adding a full iterator type with init/next/end functions (similar to what we have for hashmaps). But it ended up making the callers much harder to read. This version keeps us close to a basic for-loop. Yet another option would be adding an option to sort the array and compact out the duplicates. This would mean iterating over the array an extra time, though that's probably not a big deal (we did just do an O(n log n) sort). But we'd still have to write a for-loop to iterate, so it doesn't really make anything easier for the caller. No new test, since we'll convert the callback iterator (which is covered by t0064, among other callers) to use the new code. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-07 19:11:00 +00:00
/**
* Find the next unique oid in the array after position "cur".
* The array must be sorted for this to work. You can iterate
* over unique elements like this:
*
* size_t i;
* oid_array_sort(array);
* for (i = 0; i < array->nr; i = oid_array_next_unique(array, i))
* printf("%s", oid_to_hex(array->oids[i]);
*
* Non-unique iteration can just increment with "i++" to visit each element.
*/
static inline size_t oid_array_next_unique(struct oid_array *array, size_t cur)
{
do {
cur++;
} while (cur < array->nr &&
oideq(array->oid + cur, array->oid + cur - 1));
return cur;
}
#endif /* OID_ARRAY_H */