reftable/basics.h

   1 /*
   2 Copyright 2020 Google LLC
   3
   4 Use of this source code is governed by a BSD-style
   5 license that can be found in the LICENSE file or at
   6 https://developers.google.com/open-source/licenses/bsd
   7 */
   8
   9 #ifndef BASICS_H
  10 #define BASICS_H
  11
  12 /*
  13  * miscellaneous utilities that are not provided by Git.
  14  */
  15
  16 #include "system.h"
  17 #include "reftable-basics.h"
  18
  19 struct reftable_buf {
  20         size_t alloc;
  21         size_t len;
  22         char *buf;
  23 };
  24 #define REFTABLE_BUF_INIT { 0 }
  25
  26 /*
  27  * Initialize the buffer such that it is ready for use. This is equivalent to
  28  * using REFTABLE_BUF_INIT for stack-allocated variables.
  29  */
  30 void reftable_buf_init(struct reftable_buf *buf);
  31
  32 /*
  33  * Release memory associated with the buffer. The buffer is reinitialized such
  34  * that it can be reused for subsequent operations.
  35  */
  36 void reftable_buf_release(struct reftable_buf *buf);
  37
  38 /*
  39  * Reset the buffer such that it is effectively empty, without releasing the
  40  * memory that this structure holds on to. This is equivalent to calling
  41  * `reftable_buf_setlen(buf, 0)`.
  42  */
  43 void reftable_buf_reset(struct reftable_buf *buf);
  44
  45 /*
  46  * Trim the buffer to a shorter length by updating the `len` member and writing
  47  * a NUL byte to `buf[len]`. Returns 0 on success, -1 when `len` points outside
  48  * of the array.
  49  */
  50 int reftable_buf_setlen(struct reftable_buf *buf, size_t len);
  51
  52 /*
  53  * Lexicographically compare the two buffers. Returns 0 when both buffers have
  54  * the same contents, -1 when `a` is lexicographically smaller than `b`, and 1
  55  * otherwise.
  56  */
  57 int reftable_buf_cmp(const struct reftable_buf *a, const struct reftable_buf *b);
  58
  59 /*
  60  * Append `len` bytes from `data` to the buffer. This function works with
  61  * arbitrary byte sequences, including ones that contain embedded NUL
  62  * characters. As such, we use `void *` as input type. Returns 0 on success,
  63  * REFTABLE_OUT_OF_MEMORY_ERROR on allocation failure.
  64  */
  65 int reftable_buf_add(struct reftable_buf *buf, const void *data, size_t len);
  66
  67 /* Equivalent to `reftable_buf_add(buf, s, strlen(s))`. */
  68 int reftable_buf_addstr(struct reftable_buf *buf, const char *s);
  69
  70 /*
  71  * Detach the buffer from the structure such that the underlying memory is now
  72  * owned by the caller. The buffer is reinitialized such that it can be reused
  73  * for subsequent operations.
  74  */
  75 char *reftable_buf_detach(struct reftable_buf *buf);
  76
  77 /* Bigendian en/decoding of integers */
  78
  79 void put_be24(uint8_t *out, uint32_t i);
  80 uint32_t get_be24(uint8_t *in);
  81 void put_be16(uint8_t *out, uint16_t i);
  82
  83 /*
  84  * find smallest index i in [0, sz) at which `f(i) > 0`, assuming that f is
  85  * ascending. Return sz if `f(i) == 0` for all indices. The search is aborted
  86  * and `sz` is returned in case `f(i) < 0`.
  87  *
  88  * Contrary to bsearch(3), this returns something useful if the argument is not
  89  * found.
  90  */
  91 size_t binsearch(size_t sz, int (*f)(size_t k, void *args), void *args);
  92
  93 /*
  94  * Frees a NULL terminated array of malloced strings. The array itself is also
  95  * freed.
  96  */
  97 void free_names(char **a);
  98
  99 /*
 100  * Parse a newline separated list of names. `size` is the length of the buffer,
 101  * without terminating '\0'. Empty names are discarded. Returns a `NULL`
 102  * pointer when allocations fail.
 103  */
 104 char **parse_names(char *buf, int size);
 105
 106 /* compares two NULL-terminated arrays of strings. */
 107 int names_equal(const char **a, const char **b);
 108
 109 /* returns the array size of a NULL-terminated array of strings. */
 110 size_t names_length(const char **names);
 111
 112 /* Allocation routines; they invoke the functions set through
 113  * reftable_set_alloc() */
 114 void *reftable_malloc(size_t sz);
 115 void *reftable_realloc(void *p, size_t sz);
 116 void reftable_free(void *p);
 117 void *reftable_calloc(size_t nelem, size_t elsize);
 118 char *reftable_strdup(const char *str);
 119
 120 #define REFTABLE_ALLOC_ARRAY(x, alloc) (x) = reftable_malloc(st_mult(sizeof(*(x)), (alloc)))
 121 #define REFTABLE_CALLOC_ARRAY(x, alloc) (x) = reftable_calloc((alloc), sizeof(*(x)))
 122 #define REFTABLE_REALLOC_ARRAY(x, alloc) (x) = reftable_realloc((x), st_mult(sizeof(*(x)), (alloc)))
 123 #define REFTABLE_ALLOC_GROW(x, nr, alloc) \
 124         do { \
 125                 if ((nr) > alloc) { \
 126                         alloc = 2 * (alloc) + 1; \
 127                         if (alloc < (nr)) \
 128                                 alloc = (nr); \
 129                         REFTABLE_REALLOC_ARRAY(x, alloc); \
 130                 } \
 131         } while (0)
 132 #define REFTABLE_FREE_AND_NULL(p) do { reftable_free(p); (p) = NULL; } while (0)
 133
 134 #ifndef REFTABLE_ALLOW_BANNED_ALLOCATORS
 135 # define REFTABLE_BANNED(func) use_reftable_##func##_instead
 136 # undef malloc
 137 # define malloc(sz) REFTABLE_BANNED(malloc)
 138 # undef realloc
 139 # define realloc(ptr, sz) REFTABLE_BANNED(realloc)
 140 # undef free
 141 # define free(ptr) REFTABLE_BANNED(free)
 142 # undef calloc
 143 # define calloc(nelem, elsize) REFTABLE_BANNED(calloc)
 144 # undef strdup
 145 # define strdup(str) REFTABLE_BANNED(strdup)
 146 #endif
 147
 148 /* Find the longest shared prefix size of `a` and `b` */
 149 int common_prefix_size(struct reftable_buf *a, struct reftable_buf *b);
 150
 151 int hash_size(uint32_t id);
 152
 153 #endif