diff options
Diffstat (limited to 'Documentation/technical')
| -rw-r--r-- | Documentation/technical/api-hashmap.txt | 22 | ||||
| -rw-r--r-- | Documentation/technical/api-oid-array.txt (renamed from Documentation/technical/api-sha1-array.txt) | 44 | ||||
| -rw-r--r-- | Documentation/technical/api-parse-options.txt | 8 | ||||
| -rw-r--r-- | Documentation/technical/pack-protocol.txt | 7 |
4 files changed, 54 insertions, 27 deletions
diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt index a3f020c..ccc634b 100644 --- a/Documentation/technical/api-hashmap.txt +++ b/Documentation/technical/api-hashmap.txt @@ -21,6 +21,9 @@ that the hashmap is initialized. It may also be useful for statistical purposes `cmpfn` stores the comparison function specified in `hashmap_init()`. In advanced scenarios, it may be useful to change this, e.g. to switch between case-sensitive and case-insensitive lookup. ++ +When `disallow_rehash` is set, automatic rehashes are prevented during inserts +and deletes. `struct hashmap_entry`:: @@ -57,6 +60,7 @@ Functions `unsigned int strihash(const char *buf)`:: `unsigned int memhash(const void *buf, size_t len)`:: `unsigned int memihash(const void *buf, size_t len)`:: +`unsigned int memihash_cont(unsigned int hash_seed, const void *buf, size_t len)`:: Ready-to-use hash functions for strings, using the FNV-1 algorithm (see http://www.isthe.com/chongo/tech/comp/fnv). @@ -65,6 +69,9 @@ Functions `memihash` operate on arbitrary-length memory. + `strihash` and `memihash` are case insensitive versions. ++ +`memihash_cont` is a variant of `memihash` that allows a computation to be +continued with another chunk of data. `unsigned int sha1hash(const unsigned char *sha1)`:: @@ -184,6 +191,21 @@ passed to `hashmap_cmp_fn` to decide whether the entry matches the key. + Returns the removed entry, or NULL if not found. +`void hashmap_disallow_rehash(struct hashmap *map, unsigned value)`:: + + Disallow/allow automatic rehashing of the hashmap during inserts + and deletes. ++ +This is useful if the caller knows that the hashmap will be accessed +by multiple threads. ++ +The caller is still responsible for any necessary locking; this simply +prevents unexpected rehashing. The caller is also responsible for properly +sizing the initial hashmap to ensure good performance. ++ +A call to allow rehashing does not force a rehash; that might happen +with the next insert or delete. + `void hashmap_iter_init(struct hashmap *map, struct hashmap_iter *iter)`:: `void *hashmap_iter_next(struct hashmap_iter *iter)`:: `void *hashmap_iter_first(struct hashmap *map, struct hashmap_iter *iter)`:: diff --git a/Documentation/technical/api-sha1-array.txt b/Documentation/technical/api-oid-array.txt index dcc5294..b0c11f8 100644 --- a/Documentation/technical/api-sha1-array.txt +++ b/Documentation/technical/api-oid-array.txt @@ -1,7 +1,7 @@ -sha1-array API +oid-array API ============== -The sha1-array API provides storage and manipulation of sets of SHA-1 +The oid-array 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. @@ -9,10 +9,10 @@ not preserved over some operations. Data Structures --------------- -`struct sha1_array`:: +`struct oid_array`:: - A single array of SHA-1 hashes. This should be initialized by - assignment from `SHA1_ARRAY_INIT`. The `sha1` member contains + 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. @@ -20,22 +20,22 @@ Data Structures Functions --------- -`sha1_array_append`:: - Add an item to the set. The sha1 will be placed at the end of +`oid_array_append`:: + 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). -`sha1_array_lookup`:: - Perform a binary search of the array for a specific sha1. +`oid_array_lookup`:: + Perform a binary search of the array for a specific object ID. If found, returns the offset (in number of elements) of the - sha1. If not found, returns a negative integer. If the array is - not sorted, this function has the side effect of sorting it. + object ID. If not found, returns a negative integer. If the array + is not sorted, this function has the side effect of sorting it. -`sha1_array_clear`:: +`oid_array_clear`:: Free all memory associated with the array and return it to the initial, empty state. -`sha1_array_for_each_unique`:: +`oid_array_for_each_unique`:: Efficiently iterate over each unique element of the list, executing the callback function for each one. If the array is not sorted, this function has the side effect of sorting it. If @@ -47,25 +47,25 @@ Examples -------- ----------------------------------------- -int print_callback(const unsigned char sha1[20], +int print_callback(const struct object_id *oid, void *data) { - printf("%s\n", sha1_to_hex(sha1)); + printf("%s\n", oid_to_hex(oid)); return 0; /* always continue */ } void some_func(void) { - struct sha1_array hashes = SHA1_ARRAY_INIT; - unsigned char sha1[20]; + struct sha1_array hashes = OID_ARRAY_INIT; + struct object_id oid; /* Read objects into our set */ - while (read_object_from_stdin(sha1)) - sha1_array_append(&hashes, sha1); + 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(sha1)) { - if (sha1_array_lookup(&hashes, sha1) >= 0) + while (read_object_from_stdin(oid.hash)) { + if (oid_array_lookup(&hashes, &oid) >= 0) printf("it's in there!\n"); /* @@ -75,6 +75,6 @@ void some_func(void) * Instead, this will sort once and then skip duplicates * in linear time. */ - sha1_array_for_each_unique(&hashes, print_callback, NULL); + oid_array_for_each_unique(&hashes, print_callback, NULL); } ----------------------------------------- diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 36768b4..829b558 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -183,13 +183,13 @@ There are some macros to easily define options: scale the provided value by 1024, 1024^2 or 1024^3 respectively. The scaled value is put into `unsigned_long_var`. -`OPT_DATE(short, long, &int_var, description)`:: +`OPT_DATE(short, long, ×tamp_t_var, description)`:: Introduce an option with date argument, see `approxidate()`. - The timestamp is put into `int_var`. + The timestamp is put into `timestamp_t_var`. -`OPT_EXPIRY_DATE(short, long, &int_var, description)`:: +`OPT_EXPIRY_DATE(short, long, ×tamp_t_var, description)`:: Introduce an option with expiry date argument, see `parse_expiry_date()`. - The timestamp is put into `int_var`. + The timestamp is put into `timestamp_t_var`. `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`:: Introduce an option with argument. diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index c59ac99..5b0ba3e 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -351,14 +351,19 @@ ACK after 'done' if there is at least one common base and multi_ack or multi_ack_detailed is enabled. The server always sends NAK after 'done' if there is no common base found. +Instead of 'ACK' or 'NAK', the server may send an error message (for +example, if it does not recognize an object in a 'want' line received +from the client). + Then the server will start sending its packfile data. ---- - server-response = *ack_multi ack / nak + server-response = *ack_multi ack / nak / error-line ack_multi = PKT-LINE("ACK" SP obj-id ack_status) ack_status = "continue" / "common" / "ready" ack = PKT-LINE("ACK" SP obj-id) nak = PKT-LINE("NAK") + error-line = PKT-LINE("ERR" SP explanation-text) ---- A simple clone may look like this (with no 'have' lines): |