diff options
author | Edward Thomson <ethomson@edwardthomson.com> | 2021-09-23 21:16:36 -0400 |
---|---|---|
committer | Edward Thomson <ethomson@edwardthomson.com> | 2021-09-28 11:50:49 -0400 |
commit | cb2c926336f5f7f1a75c871cb74d567b52bb8c5c (patch) | |
tree | ec6ddaaabb8db6406bb0d7092fc5d4eb604d39ac | |
parent | b7bad55e4bb0a285b073ba5e02b01d3f522fc95d (diff) | |
download | libgit2-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.md | 55 |
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. |