summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEdward Thomson <ethomson@edwardthomson.com>2021-09-23 21:16:36 -0400
committerEdward Thomson <ethomson@edwardthomson.com>2021-09-28 11:50:49 -0400
commitcb2c926336f5f7f1a75c871cb74d567b52bb8c5c (patch)
treeec6ddaaabb8db6406bb0d7092fc5d4eb604d39ac
parentb7bad55e4bb0a285b073ba5e02b01d3f522fc95d (diff)
downloadlibgit2-cb2c926336f5f7f1a75c871cb74d567b52bb8c5c.tar.gz
docs: document `git_buf`
We have been inconsistent about the way that we handle `git_buf`s provided by users. _Usually_ we require that it has been properly initialized with `GIT_BUF_INIT`, but _sometimes_ we simply overwrite the data in it regardless. And even more rarely, we will grow a user-provided buffer and concatenate data onto it (see `git_diff_format_email`). Document the path forward for `git_buf`, which is that we always require that the buffer is intitialized with `GIT_BUF_INIT`. `git_diff_format_email` will be kept backward compatible but users are encouraged to switch to the new `git_email` APIs.
-rw-r--r--docs/buffers.md55
1 files changed, 55 insertions, 0 deletions
diff --git a/docs/buffers.md b/docs/buffers.md
new file mode 100644
index 000000000..334269e09
--- /dev/null
+++ b/docs/buffers.md
@@ -0,0 +1,55 @@
+Memory allocation and ownership
+-------------------------------
+
+Any library needs to _take_ data from users, and then _return_ data to
+users. With some types this is simple - integer parameters and return
+types are trivial. But with more complex data types, things are more
+complicated. Even something seemingly simple, like a C string, requires
+discipline: we cannot simple return an allocated hunk of memory for
+callers to `free`, since some systems have multiple allocators and users
+cannot necessarily reason about the allocator used and which corresponding
+deallocation function to call to free the memory.
+
+## Objects
+
+Most types in libgit2 are "opaque" types, which we treat as "objects" (even
+though C is "not an object oriented language"). You may create an object -
+for example, with `git_odb_new`, or libgit2 may return you an object as an
+"out" parameter - for example, with `git_repository_open`. With any of
+these objects, you should call their corresponding `free` function (for
+example, `git_odb_free` or `git_repository_free`) when you are done using
+them.
+
+## Structures
+
+libgit2 will often take _input_ as structures (for example, options
+structures like `git_merge_options`). Rarely, libgit2 will return data in
+a structure. This is typically used for simpler data types, like `git_buf`
+and `git_strarray`. Users should allocate the structure themselves (either
+on the stack or the heap) and pass a pointer to it. Since libgit2 does not
+allocate the structure itself, only the data inside of it, the deallocation
+functions are suffixed with `_dispose` instead of `_free`, since they only
+free the data _inside_ the structure.
+
+## Strings or continuous memory buffers (`git_buf`)
+
+libgit2 typically _takes_ NUL-terminated strings ("C strings") with a
+`const char *`, and typically _takes_ raw data with a `const char *` and a
+corresponding `size_t` for its size. libgit2 typically _returns_ strings
+or raw data in a `git_buf` structure. The given data buffer will always be
+NUL terminated (even if it contains binary data) and the `size` member will
+always contain the size (in bytes) of the contents of the pointer (excluding
+the NUL terminator).
+
+In other words, if a `git_buf` contains the string `foo` then the memory
+buffer will be { `f`, `o`, `o`, `\0` } and the size will be `3`.
+
+Callers _should_ initialize the buffer with `GIT_BUF_INIT` or by setting
+all the members to `0` before passing a pointer to the buffer to
+libgit2. Callers must call `git_buf_dispose` when they have finished.
+
+Note that the deprecated `git_diff_format_email` API does not follow
+this behavior; it _requires_ initial calls to initialize a buffer with
+`GIT_BUF_INIT`. Subsequent calls may pass the same buffer and it
+will concatenate data to it. Users should move to the new `git_email`
+APIs that follow the `git_buf` standards.