about summary refs log tree commit diff
path: root/third_party/git/Documentation/technical/api-allocation-growing.txt
diff options
context:
space:
mode:
authorVincent Ambo <tazjin@google.com>2020-05-25T23·06+0100
committerVincent Ambo <tazjin@google.com>2020-05-25T23·06+0100
commit93ba78d6f4632ef1c5228965e3edc8c0faf88c1e (patch)
tree85730c182a9f5f492ade8e8ccdb1c2356f9900bd /third_party/git/Documentation/technical/api-allocation-growing.txt
parent6f8fbf4aa4b1654ab27d4829e114538761817de0 (diff)
revert(3p/git): Revert merge of git upstream at v2.26.2 r/852
This causes cgit to serve error pages, which is undesirable.

This reverts commit 5229c9b232de5bfa959ad6ebbb4c8192ac513352, reversing
changes made to f2b211131f2347342dde63975b09cf603149f1a3.
Diffstat (limited to 'third_party/git/Documentation/technical/api-allocation-growing.txt')
-rw-r--r--third_party/git/Documentation/technical/api-allocation-growing.txt39
1 files changed, 39 insertions, 0 deletions
diff --git a/third_party/git/Documentation/technical/api-allocation-growing.txt b/third_party/git/Documentation/technical/api-allocation-growing.txt
new file mode 100644
index 000000000000..5a59b548448f
--- /dev/null
+++ b/third_party/git/Documentation/technical/api-allocation-growing.txt
@@ -0,0 +1,39 @@
+allocation growing API
+======================
+
+Dynamically growing an array using realloc() is error prone and boring.
+
+Define your array with:
+
+* a pointer (`item`) that points at the array, initialized to `NULL`
+  (although please name the variable based on its contents, not on its
+  type);
+
+* an integer variable (`alloc`) that keeps track of how big the current
+  allocation is, initialized to `0`;
+
+* another integer variable (`nr`) to keep track of how many elements the
+  array currently has, initialized to `0`.
+
+Then before adding `n`th element to the item, call `ALLOC_GROW(item, n,
+alloc)`.  This ensures that the array can hold at least `n` elements by
+calling `realloc(3)` and adjusting `alloc` variable.
+
+------------
+sometype *item;
+size_t nr;
+size_t alloc
+
+for (i = 0; i < nr; i++)
+	if (we like item[i] already)
+		return;
+
+/* we did not like any existing one, so add one */
+ALLOC_GROW(item, nr + 1, alloc);
+item[nr++] = value you like;
+------------
+
+You are responsible for updating the `nr` variable.
+
+If you need to specify the number of elements to allocate explicitly
+then use the macro `REALLOC_ARRAY(item, alloc)` instead of `ALLOC_GROW`.