docs/buffers.md

   1 Memory allocation and ownership
   2 -------------------------------
   3
   4 Any library needs to _take_ data from users, and then _return_ data to
   5 users.  With some types this is simple - integer parameters and return
   6 types are trivial.  But with more complex data types, things are more
   7 complicated.  Even something seemingly simple, like a C string, requires
   8 discipline: we cannot simple return an allocated hunk of memory for
   9 callers to `free`, since some systems have multiple allocators and users
  10 cannot necessarily reason about the allocator used and which corresponding
  11 deallocation function to call to free the memory.
  12
  13 ## Objects
  14
  15 Most types in libgit2 are "opaque" types, which we treat as "objects" (even
  16 though C is "not an object oriented language").  You may create an object -
  17 for example, with `git_odb_new`, or libgit2 may return you an object as an
  18 "out" parameter - for example, with `git_repository_open`.  With any of
  19 these objects, you should call their corresponding `_free` function (for
  20 example, `git_odb_free` or `git_repository_free`) when you are done using
  21 them.
  22
  23 ## Structures
  24
  25 libgit2 will often take _input_ as structures (for example, options
  26 structures like `git_merge_options`).  Rarely, libgit2 will return data in
  27 a structure.  This is typically used for simpler data types, like `git_buf`
  28 and `git_strarray`.  Users should allocate the structure themselves (either
  29 on the stack or the heap) and pass a pointer to it.  Since libgit2 does not
  30 allocate the structure itself, only the data inside of it, the deallocation
  31 functions are suffixed with `_dispose` instead of `_free`, since they only
  32 free the data _inside_ the structure.
  33
  34 ## Strings or continuous memory buffers (`git_buf`)
  35
  36 libgit2 typically _takes_ NUL-terminated strings ("C strings") with a
  37 `const char *`, and typically _takes_ raw data with a `const char *` and a
  38 corresponding `size_t` for its size.  libgit2 typically _returns_ strings
  39 or raw data in a `git_buf` structure.  The given data buffer will always be
  40 NUL terminated (even if it contains binary data) and the `size` member will
  41 always contain the size (in bytes) of the contents of the pointer (excluding
  42 the NUL terminator).
  43
  44 In other words, if a `git_buf` contains the string `foo` then the memory
  45 buffer will be { `f`, `o`, `o`, `\0` } and the size will be `3`.
  46
  47 Callers _must_ initialize the buffer with `GIT_BUF_INIT` (or by setting
  48 all the members to `0`) when it is created, before passing a pointer
  49 to the buffer to libgit2 for the first time.
  50
  51 Subsequent calls to libgit2 APIs that take a buffer can re-use a
  52 buffer that was previously used.  The buffer will be cleared and grown
  53 to accommodate the new contents (if necessary).  The new data will
  54 written into the buffer, overwriting the previous contents.  This
  55 allows callers to reduce the number of allocations performed by the
  56 library.
  57
  58 Callers must call `git_buf_dispose` when they have finished.
  59
  60 Note that the deprecated `git_diff_format_email` API does not follow
  61 this behavior; subsequent calls will concatenate data to the buffer
  62 instead of rewriting it.  Users should move to the new `git_email`
  63 APIs that follow the `git_buf` standards.